Directory Services

IDirectorySearch::GetFirstRow

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.

HRESULT GetFirstRow( 
  ADS_SEARCH_HANDLE hSearchHandle
);

Parameters

hSearchHandle: [in] Contains the search handle obtained by calling IDirectorySearch::ExecuteSearch.

Return Values

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

For more information, see ADSI Error Codes.

Return Code	Description
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.

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.

Example Code [C++]

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

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Iads.h.