Active Directory Provider::Search

Active Directory Provider::Search

Performs a directory search in Microsoft® Active Directory®. Used by Microsoft® Provisioning Framework (MPF).

Wrapper for IDirectorySearch.

XML Input Schema
The following code fragment shows the format for sending data to this procedure. For more information on individual elements and attributes, see the Elements and Attributes table.
<executeData>1..1
  <path>1..1</path>
  <filter>1..1</filter>
  <propertyList>0..1
	<property name="..">0..unbounded</property>
  </propertyList>
  <preferences>0..1
	<preference>1..unbounded
	<searchPref>1..unbounded</searchPref>
	<type>1..unbounded</type>
	<value>1..unbounded</value>
	</preference>
  </preferences>
</executeData>
XML Output Schema
The following code fragment shows the format for data this procedure returns. For more information on individual elements and attributes, see the Elements and Attributes table.
<executeData>1..1
  <objects>1..1
	<object class=".." name="..">0..unbounded
	<property name="..">0..unbounded
		<value>0..unbounded</value>
	</property>
	</object>
  </objects>
</executeData>
Elements and Attributes
The following table describes the XML schema elements and attributes. Unless otherwise indicated, the data type is string.
Element Description, relationships, and attributes

executeData Description:
Encapsulates the procedure's input and output data.
Children:
filter (minOccurs="1" maxOccurs="1", input only)
objects (minOccurs="1" maxOccurs="1", output only)
path (minOccurs="1" maxOccurs="1", input only)
preferences (minOccurs="0" maxOccurs="1", input only)
propertyList (minOccurs="0" maxOccurs="1", input only)
filter
Description:
Search filter string in lightweight directory access protocol (LDAP) format. The following sample code illustrates the use of filter:
<filter>objectClass=user</filter>
Parent:
executeData
object Description:
Found object that matches the search criteria. It may contain zero or more requested property elements.
Parent:
objects

Child:
property (minOccurs="0" maxOccurs="*")

Attributes:

class Last value of the objectClass property, which is the class of the object. Examples: "user", "group", "contact", and so on.

name Object name. Examples: "Administrator", "Guest", and so on.

objects Description:
Returned list of objects that match the search criteria.
Parent:
executeData

Child:
object (minOccurs="0" maxOccurs="*")

path Description:
LDAP path of the starting object for the search.
Parent:
executeData
preference
Description:
Individual search preference. This element modifies the behavior of the search by changing one of the search preferences from the default value to the value specified. The following sample code illustrates the use of preference:
<preference>
   <searchPref>ADS_SEARCHPREF_SEARCH_SCOPE</searchPref>
   <type>ADSTYPE_INTEGER<type/>
   <value>ADS_SCOPE_ONELEVEL</value>
</preference>
Parent:
preferences

Children:
searchPref (minOccurs="1" maxOccurs="*")
type (minOccurs="1" maxOccurs="*")
value (minOccurs="1" maxOccurs="*")
preferences Description:
List of search preferences that modify the behavior of the search. See also preference.
Parent:
executeData

Child:
preference (minOccurs="1" maxOccurs="*")

property Description:
Active Directory property. For output, properties with multiple values are returned with corresponding value nodes.
Parents:
object (output), propertyList (input)

Child:
value (minOccurs="0" maxOccurs="*")

Attributes:

name LDAP display name of the property.

propertyList Description:
List of Active Directory properties to retrieve. If propertyList is not provided or no property elements exist, all properties are returned.
Parent:
executeData

Child:
property (minOccurs="0" maxOccurs="*")
searchPref
Description:
Search preference to change. The following sample code illustrates the use of searchPref:
<preference>
   <searchPref>ADS_SEARCHPREF_SEARCH_SCOPE</searchPref>
   <type>ADSTYPE_INTEGER<type/>
   <value>ADS_SCOPE_ONELEVEL</value>
</preference>
Search preference is specified by one of the following ADS_SEARCHPREF_ENUM values.

ADS_SEARCHPREF_ASYNCHRONOUS 0 Specifies that searches should be carried out asynchronously. By default, searches are synchronous.
In a synchronous search, the GetFirstRow and GetNextRow methods of IDirectorySearch do not return until the server returns the entire result (or, for a paged search, the entire page).

An asynchronous search blocks until one row of the search results is available, or until the timeout interval specified by the ADS_SEARCHPREF_TIMEOUT search preference elapses.

ADS_SEARCHPREF_DEREF_ALIASES 1 Specifies that aliases of found objects are to be resolved. Use one of the following ADS_DEREFENUM enumerations to specify how this should be done.

ADS_DEREF_NEVER 0 Does not dereference aliases when searching or locating the base object of the search.

ADS_DEREF_SEARCHING 1 Dereferences aliases when searching subordinates of the base object, but not when locating the base itself.

ADS_DEREF_FINDING 2 Dereferences aliases when locating the base object of the search, but not when searching its subordinates.

ADS_DEREF_ALWAYS 3 Dereferences aliases when both searching subordinates and locating the base object of the search.

ADS_SEARCHPREF_SIZE_LIMIT 2 Size limit the server should allow for a search. For Active Directory, the size limit specifies the maximum number of returned objects. The server stops searching once the size limit is reached and returns the results accumulated up to that point.

ADS_SEARCHPREF_TIME_LIMIT 3 Time limit (in seconds) that the server should allow for the search. When the time limit is reached, the server stops searching and returns whatever results it has accumulated up to that point.

ADS_SEARCHPREF_ATTRIBTYPES_ONLY 4 Indicates that the search should obtain only the name of attributes to which values have been assigned.

ADS_SEARCHPREF_SEARCH_SCOPE 5 Scope for the search. For the appropriate settings, see the following ADS_SCOPEENUM enumeration values.

ADS_SCOPE_BASE 0 Limits the search to the base object. The result contains at most one object.

ADS_SCOPE_ONELEVEL 1 Searches one level of the immediate children, excluding the base object.

ADS_SCOPE_SUBTREE 2 Default. Searches the whole subtree, including all the children and the base object itself.

ADS_SEARCHPREF_TIMEOUT 6 Time limit (in seconds) that a client waits for the server to return the result. This option is set in an ADS_SEARCHPREF_INFO structure.

ADS_SEARCHPREF_PAGESIZE 7 Page size in a paged search. For each request by the client, the server returns at most the number of objects as set by the page size.

ADS_SEARCHPREF_PAGED_TIME_LIMIT 8 Time limit (in seconds) that the server allows to search a page of results (as opposed to the time limit for the entire search). When the limit is reached, the server stops searching and returns the result obtained up to that point, along with a cookie containing the information about where to resume searching.

ADS_SEARCHPREF_CHASE_REFERRALS 9 Specifies that referrals can be chased. If the root search is not specified in the naming context of the server or when the search results cross a naming context (for example, when you have child domains and search in the parent domain), the server sends a referral message to the client which the client can choose to ignore or chase. For more information on referrals chasing, see ADS_CHASE_REFERRALS_ENUM.

ADS_SEARCHPREF_SORT_ON 10 Specifies that the server sorts the result set. Use the ADS_SORTKEY structure to specify the sort keys. This search preference works only for directory servers that support the LDAP control for server-side sorting. Active Directory supports the sort control, but it can impact server performance, particularly if the results set is large. Note that Active Directory supports only a single sort key.

ADS_SEARCHPREF_CACHE_RESULTS 11 Specifies if the result should be cached on the client side. By default, ADSI caches the result set. Turning off this option may be more desirable for large result sets.

ADS_SEARCHPREF_DIRSYNC 12 Specifies a directory synchronization (DirSync) search, which returns all changes since a specified state. In the ADSVALUE structure, set the dwType member to ADSTYPE_PROV_SPECIFIC. The ProviderSpecific member is an ADS_PROV_SPECIFIC structure whose lpValue member specifies a cookie that indicates the state from which changes are retrieved. The first time you use the DirSync control, set the dwLength and lpValue members of the ADS_PROV_SPECIFIC structure to zero and NULL respectively. After reading through the results set returned by the search until IDirectorySearch::GetNextRow returns S_ADS_NOMORE_ROWS, call IDirectorySearch::GetColumn to retrieve the ADS_DIRSYNC_COOKIE attribute which contains a cookie to use in the next DirSync search.
This flag cannot be combined with ADS_SEARCHPREF_PAGESIZE.

The caller must have the privilege.

ADS_SEARCHPREF_TOMBSTONE 13 Specifies whether the search should also return deleted objects that match the search filter. When objects are deleted, Active Directory moves them to a "Deleted Objects" container. By default, deleted objects are not included in the search results. In the structure, set the dwType member to ADSTYPE_BOOLEAN. To include deleted objects, set ADSVALUE.Boolean to TRUE.
Not all attributes are preserved when the object is deleted. You can retrieve the objectGUID and RDN attributes. The distinguishedName attribute is the DN of the object in the "Deleted Objects" container, not the previous DN. The isDeleted attribute is TRUE for a deleted object.

ADS_SEARCHPREF_VLV 14 Specifies that the search should use the LDAP virtual list view (VLV) control. ADS_SEARCHPREF_VLV can be used to access both string-type and offset-type VLV searches, by setting the appropriate fields. These two options cannot be used simultaneously, because it is not possible to set the VLV control to request a result set that is both located at a specific offset and follows a particular value in the sort sequence.
To perform a string search, set the lpszTarget field in ADS_VLV to the string to be searched for. To perform an offset type search, set the offset field in ADS_VLV. If you use an offset search, you must set lpszTarget to NULL.

ADS_SEARCHPREF_SORT_ON must be set to TRUE when using ADS_SEARCHPREF_VLV. The sort order of the search results determines the order used for the VLV search. If performing an offset-type search, the offset is used as an index into the sorted list. If performing a string-type search, the server attempts to return the first entry which is greater-than-or-equal-to the string, based on the sort order.

Caching of search results is automatically disabled when ADS_SEARCHPREF_VLV is specified.

If you assign ADS_SEARCHPREF_CACHE_RESULTS a TRUE value when using ADS_SEARCHPREF_VLV, SetSearchPreference will fail with the error E_ADS_BAD_PARAMETER.

ADS_SEARCHPREF_ATTRIBUTE_QUERY 15 Specifies that an attribute-scoped query search should be performed. The search is performed against those objects named in a specified attribute of the base object. This attribute, which must be a DN-valued attribute, is specified in the ADSVALUE structure as a CaseIgnoreString. Only one attribute may be specified. Search scope is automatically set to ADS_SCOPE_BASE when using this preference. Attempting to set the scope otherwise will fail with the error E_ADS_BAD_PARAMETER. With the exception of the ADS_SEARCHPREF_VLV preference, all other preferences that use LPAD controls—such as ADS_SEARCHPREF_DIRSYNC, ADS_SEARCHPREF_TOMBSTONE, and so on—are not allowed when this preference is specified.

Parent:
preference
type
Description:
Data type of the value element for this search preference. The type element must be an ADSTYPEENUM value. Only ADSTYPE_INTEGER and ADSTYPE_BOOLEAN are currently supported. The following sample code illustrates the use of type:
<preference>
   <searchPref>ADS_SEARCHPREF_SEARCH_SCOPE</searchPref>
   <type>ADSTYPE_INTEGER<type/>
   <value>ADS_SCOPE_ONELEVEL</value>
</preference>
Supported ADSTYPEENUM values:

ADSTYPE_BOOLEAN 6 The data has a Boolean value.

ADSTYPE_INTEGER 7 The data has an integer value.

Parent:
preference
value
Description:
Input: New value for the search preference. The following sample code illustrates the use of value:
<preference>
  <searchPref>ADS_SEARCHPREF_SEARCH_SCOPE</searchPref>
  <type>ADSTYPE_INTEGER<type/>
  <value>ADS_SCOPE_ONELEVEL</value>
</preference>
Output: A value of a property.

Parents:
preference (input only)
property (output only)
See Also

Active Directory Provider, Preferred DC Active Directory Provider

Top of Page
© 1999-2002 Microsoft Corporation. All rights reserved.