Directory Services

IDirectorySearch::GetNextRow

The GetNextRow method gets the next row of the search result. If IDirectorySearch::GetFirstRow has not been called, GetNextRow will issue a new search beginning from the first row. Otherwise, this method will advance to the next row.

HRESULT GetNextRow( 
  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 next row was successfully obtained.
E_ADS_BAD_PARAMETER	The search handle is invalid.
S_ADS_NOMORE_ROWS	There are no more rows to retrieve or the search is waiting for a response. If ADsGetLastError returns ERROR_MORE_DATA, the search is waiting for a response and GetNextRow should be called again.

Remarks

When the ADS_SEARCHPREF_CACHE_RESULTS flag is not set, only forward scrolling is permitted, because the client might not cache all the query results.

The directory provider may limit the maximum number of rows available in a search. For example, on a Windows 2000 domain, the maximum number of rows that will be provided in an Active Directory search is 1000 rows. If the search results in more than the row limit, a paged search must be performed in order to obtain all rows in the search. For more information about paged searches, see Paging with IDirectorySearch.

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.