Directory Services

Synchronous and Asynchronous Searches with IDirectorySearch

When you perform a search using the IDirectorySearch interface, the IDirectorySearch::ExecuteSearch method does not send the search request to the server. This method only saves the search parameters. The search request is actually sent when you call IDirectorySearch::GetFirstRow or IDirectorySearch::GetNextRow.

For Active Directory searches, the primary difference between synchronous and asynchronous is when the first row of the result is returned, that is, when the first GetFirstRow or GetNextRow call returns.

In a synchronous search, if paging is not enabled, the first row is returned when the server has constructed and returned the entire result set to the client. If paging is enabled, the first row is returned when the first page of the result set is returned.

In an asynchronous search, if paging is not enabled, the first row is returned when the server has constructed the first row of the result set. If paging is enabled, the first row is returned when the first page of the result set is returned.

The default search type is synchronous. To specify an asynchronous search, set an ADS_SEARCHPREF_ASYNCHRONOUS search option with an ADSTYPE_BOOLEAN value of TRUE in the ADS_SEARCHPREF_INFO array passed to the IDirectorySearch::SetSearchPreference method. This operation is shown in the following code example.

[C++]
ADS_SEARCHPREF_INFO SearchPref;
SearchPref.dwSearchPref = ADS_SEARCHPREF_ASYNCHRONOUS;
SearchPref.vValue.dwType = ADSTYPE_BOOLEAN;
SearchPref.vValue.Boolean = TRUE;