Directory Services

Using IDirectorySearch and IDirectoryObject for Range Retrieval

The IDirectoryObject or IDirectorySearch interfaces can be used to retrieve a range of property values. To do this, specify the attribute and range for one of the attributes requested in the query.

Range Retrieval with IDirectoryObject

The IDirectoryObject interface can be used for range retrieval by specifying the attribute and range for one of the attributes in the pAttributesName array when calling the IDirectoryObject::GetObjectAttributes method.

PADS_ATTR_INFO pAttrInfo;
DWORD dwRetrieved;
LPWSTR pszAttrs[2];
 
pszAttrs[0] = L"Name";
pszAttrs[1] = L"member;range=0-100";

hr = pdo->GetObjectAttributes(pszAttrs, 2, &pAttrInfo, &dwRetrieved);

For more information and a code example that shows how to use the IDirectoryObject interface for range retrieval, see Example Code for Ranging with IDirectoryObject.

Range Retrieval with IDirectorySearch

The IDirectorySearch interface can be used for range retrieval by specifying the attribute and range for one of the retrieved attributes in the pAttributesName array when calling the IDirectorySearch::ExecuteSearch method.

ADS_SEARCH_HANDLE hSearch;
LPWSTR pszAttrs[2];
 
pszAttrs[0] = L"Name";
pszAttrs[1] = L"member;range=0-100";

hr = pdo->ExecuteSearch(L"(objectClass=user)", pszAttrs, 2, &hSearch);

When using the IDirectorySearch interface for range retrieval, there is one problem that must be specifically addressed. When the range requested exceeds the number of remaining values, IDirectorySearch::GetColumn will return E_ADS_COLUMN_NOT_SET. To retrieve the remaining values, it is necessary to use the range wildcard '*'. For example, if a group contains 150 members, member values 0-100 can be retrieved normally using ranged retrieval. If range 101-200 is then requested, IDirectorySearch::GetColumn will return E_ADS_COLUMN_NOT_SET. This problem can be avoided by using the IDirectorySearch::GetNextColumnName method. Normally, GetNextColumnName will return the original query string. However, when the range requested exceeds the number of remaining values, GetNextColumnName will return a modified version of the query string by replacing the high range value with the range wildcard '*'. In the example above, the first query would be performed with an attribute string of "member;range=0-100" and GetNextColumnName will return "member;range=0-100". In the second query, the attribute string would be "member;range=101-200", but GetNextColumnName will return "member;range=101-*". This case can be determined by comparing the original attribute string to the result of GetNextColumnName. If the strings are different, the last block of values should be re-requested with the range wildcard.

For more information and a code example that shows how to use the IDirectorySearch interface for range retrieval, see Example Code for Ranging with IDirectorySearch.