Platform SDK: Active Directory, ADSI, and Directory Services

IDirectorySearch::GetFirstRow

The IDirectorySearch::GetFirstRow method gets the first row of a search result. This method will issue or re-issue a new search, even if you have called this method before.

HRESULT GetFirstRow(
  ADS_SEARCH_HANDLE hSearchHandle
);

Parameters

hSearchHandle: [in] Provides a handle to the search context.

Return Values

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

S_OK: The first row was successfully obtained.
E_ADS_BAD_PARAMETER: The search handle is invalid.
S_ADS_NOMORE_ROWS: No rows can be found.

For other return values, see ADSI Error Codes.

Remarks

When the ADS_SEARCHPREF_CACHE_RESULTS flag is not set (that is, FALSE), only forward scrolling is permitted, because the client might not cache all the query results. Calling IDirectorySearch::GetFirstRow more than once from the same row requires some back-scrolling and could result in erroneous outcomes for a paged or an asynchronous search initiated through OLE DB when the results are not guaranteed to remain in the cache.

Example Code [C++]

hr = m_pSearch->ExecuteSearch(L"(objectCategory=contact)", pszAttr, dwCount, &hSearch );
if ( SUCCEEDED(hr) )
{
    hr = m_pSearch->GetFirstRow(hSearch);
      /* Get the data */
    m_pSearch->CloseSearchHandle(hSearch);
}

Requirements