Active Directory Provider::Search

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

Wrapper for IDirectorySearch.

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

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

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

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

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

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

ADS_SEARCHPREF_SEARCH_SCOPE

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

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.For more information of ADS_SEARCHPREF_INFO, see

ADS_SEARCHPREF_PAGESIZE

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

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

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

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

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

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

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

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

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)

Remarks

Schema Definition

Input

The schema should be as follows. A search can contain multiple search preferences. However, each preference can have only a single type and value.

<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..1</searchPref>
	<type>1..1</type>
	<value>1..1</value>
	</preference>
  </preferences>
</executeData>

Output

Sample Code

Example XML Request

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.

<request>
		<procedure>
				<execute namespace="Active Directory Provider" procedure="Search" impesonate="1">
						<executeData>
		<path>LDAP://ad01.fabrikam.com/OU=AlpineSkiHouse,OU=ConsolidatedMessenger,OU=Hosting,DC=FAbrikam,DC=Com</path>
								<filter>objectClass=user</filter>
								<propertyList>
										<property name="sAMAccountName" />
								</propertyList>
								<preferences>
										<preference>
												<searchPref>ADS_SEARCHPREF_SEARCH_SCOPE</searchPref>
												<type>ADSTYPE_INTEGER</type>
												<value>ADS_SCOPE_ONELEVEL</value>
										</preference>
								</preferences>
						</executeData>
						<after source="executeData" destination="data" mode="insert" />
				</execute>
		</procedure>
</request>

Example XML Response

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.

<response>
  <data>
	<executeData>
	<path>LDAP://ad01.fabrikam.com/OU=AlpineSkiHouse,OU=ConsolidatedMessenger,OU=Hosting,DC=FAbrikam,DC=Com</path>
	<filter>objectClass=user</filter>
	<propertyList>
		<property name="sAMAccountName"/>
	</propertyList>
	<preferences>
		<preference>
		<searchPref>ADS_SEARCHPREF_SEARCH_SCOPE</searchPref>
		<type>ADSTYPE_INTEGER</type>
		<value>ADS_SCOPE_ONELEVEL</value>
		</preference>
	</preferences>
	<objects>
		<object class="user"
			name="JohnC@AlpineSkiHouse.com">

		<property name="sAMAccountName">
			<value>JohnC_AlpineSkiHouse</value>
		</property>
		</object>
		<object class="user"
			name="KimA@AlpineSkiHouse.com">

		<property name="sAMAccountName">
			<value>KimA_AlpineSkiHouse_</value>
		</property>
		</object>
	</objects>
	</executeData>
  </data>
</response>

Applies To