IDirectorySearch::GetFirstRow method (iads.h)

Article
10/13/2021

The GetFirstRow method gets the first row of a search result. This method will issue or reissue a new search, even if this method has been called before.

Syntax

HRESULT GetFirstRow(
  [in] ADS_SEARCH_HANDLE hSearchResult
);

Parameters

[in] hSearchResult

Contains the search handle obtained by calling IDirectorySearch::ExecuteSearch.

Return value

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

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

Examples

hr = m_pSearch->ExecuteSearch(L"(objectCategory=contact)", pszAttr, dwCount, &hSearch);
if(SUCCEEDED(hr))
{
    while(SUCCEEDED(hr = m_pSearch->GetNextRow(hSearch)))
    {
        if(S_OK == hr)
        {
            // Get the data.
        }
        else if(S_ADS_NOMORE_ROWS == hr)
        {
            // Call ADsGetLastError to see if the search is waiting for a response.
            DWORD dwError = ERROR_SUCCESS;
            WCHAR szError[512];
            WCHAR szProvider[512];

            ADsGetLastError(&dwError, szError, 512, szProvider, 512);
            if(ERROR_MORE_DATA != dwError)
            {
                break;
            }
        }
        else
        {
            break;
        }
    }
    
    m_pSearch->CloseSearchHandle(hSearch);
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	iads.h
DLL	Activeds.dll; Adsldp.dll; Adsldpc.dll