Platform SDK: Active Directory, ADSI, and Directory Services

IDirectorySearch::ExecuteSearch

The IDirectorySearch::ExecuteSearch method executes a search and passes the results to the caller. Some providers, such as LDAP, will defer the actual execution until the caller invokes the IDirectorySearch::GetFirstRow method or the IDirectorySearch::GetNextRow method.

HRESULT ExecuteSearch(
  LPWSTR pszSearchFilter,
  LPWSTR * pAttributeNames,
  DWORD dwNumberAttributes,
  PADS_SEARCH_HANDLE phSearchHandle
);

Parameters

pszSearchFilter: [in] A search filter string in LDAP format, such as "(objectClass=user)".
pAttributeNames: [in] An array of attribute names for which data is requested. If NULL, all attributes are requested and dwNumberAttributes must be -1.
dwNumberAttributes: [in] The size of the pAttributeNames array. If -1, all attributes are requested and pAttributeNames must be NULL.
phSearchHandle: [out] The address of a method-allocated handle to the search context. The caller passes this handle to other methods of IDirectorySearch to examine the search result. If NULL, the search could not be executed.

Return Values

This method returns the standard return values, as well as the following:

S_OK: The search was successfully executed.
E_ADS_BAD_PARAMETER: The search handle is invalid.

For other return values, see ADSI Error Codes.

Remarks

When the search filter (pszSearchFilter) contains an attribute of ADS_UTC_TIME type, it value must be of the "yymmddhhmmssZ" format where "y", "m", "d", "h", "m" and "s" stand for year, month, day, hour, minute, and second, respectively. In this format, for example, "10:20:00 May 13^th, 1999" become "990513102000Z". The final letter "Z" is the required syntax and stands for Zulu Time or Universal Coordinated Time.

The caller is responsible for calling IDirectorySearch::CloseSearchHandle to release the memory allocated for the search handle and the result.

Example Code [C++]

The following C++ code snippet illustrates how to invoke IDirectorySearch::ExecuteSearch.

LPWSTR pszAttr[] = { L"ADsPath", L"Name", L"samAccountName" };
ADS_SEARCH_HANDLE hSearch;
DWORD dwCount= sizeof(pszAttr)/sizeof(LPWSTR);
 
// Search for all users with a last name that starts with h.
hr = m_pSearch->ExecuteSearch(L"(&(objectClass=user)(sn=h*))", pszAttr, dwCount, &hSearch );

Requirements