| Directory Services |
Beginning with Microsoft® Windows Server 2003 family operating systems, Microsoft Active Directory directory service supports virtual list view (VLV) searches. This enables a user to view search results as address-book style virtual list views. It is specifically designed for very large result sets. Search data is retrieved in contiguous subsets of a sorted directory search.
ADSI VLV is a wrapper for an LDAP control that implements the VLV functionality. This control enables the retrieval of a small section of a large result set, without having to retrieve the search results before or after that subsection. For example, if a user searched for an entry in a global address directory at a large University, they could enter a name, such as Smith, and, using VLV functionality, the server would return a list of ten names with the first entry for Smith at the top of the list, rather than returning a list of names that contains thousands of entries. ADSI enables you to create applications that require VLV in order to run efficiently without having to resort to directly accessing the underlying LDAP protocol.
To access VLV features in ADSI, use the SetSearchPreference method on the IDirectorySearch interface. To enable VLV, set the ADS_SEARCHPREF_VLV value for ADS_SEARCHPREF_ENUM. Search parameters are held in the ADS_VLV structure.
There are two mutually exclusive ways to identify the target entry of the VLV search: offset-type and string-type. In the first case, you specify the numeric offset, which is the dwOffset member of the ADS_VLV structure, into the sorted list that corresponds to the target entry. In the second case, you specify a string in the pszTarget member of the ADS_VLV structure, and the server returns the first entry in the sorted list that is greater than or equal to the string. These two options cannot be used simultaneously, because it is not possible to set the VLV control to request a result set that is both located at a specific offset and follows a particular value in the sort sequence.
Offsets are transmitted between your application and the server as a ratio between the offset and the content count. Ratios are useful because the server may not have an accurate estimate of the number of entries that exist in the list or the list size may be changing during the time the user is browsing it. Because you must indicate the beginning and end of the list, you can use an estimated value for the content count in the first search request, along with an offset value. The server uses this data to compute the corresponding offsets within the list, based on its idea of content count, which is sent in its response to the client through the dwContentCount member of the ADS_VLV structure. For example, if you estimate the list size to be 3000, and you want the offset to be list entry 1500, you would set dwContentCount to 3000 and dwOffset to 1500. If the server estimates the actual list size to be 4500, it will recalculate the offset to 2250, and return the new estimates in dwContentCount and dwOffset.
Be aware that any offset values returned by the server may be approximate. Do not design your application to only operate correctly when offsets are exact.
There are also optional opaque parameters that may be used for the context ID (lpContextID) and context ID length (dwContextIDLength). If not used, the lpContextID must be set to NULL and dwContextIDLength set to zero. The server will send this information back to your program, which should return it to the server unchanged on the next VLV search by passing it back in through lpContextID and dwContextIDLength. This option may improve performance, depending on the server implementation.
VLV is only defined on an interaction with a single server. If a server returns referrals as a part of its response to the search request, the application must deciding when and how to apply this control to the referred-to servers, and how to collate the results from multiple servers.
The LDAP VLV control requires server-side sorting. Because ADSI does not enforce this requirement, if server-side sorting is not selected, SetSearchPreference will accept it, but it will be failed by the server.
For more information about the LDAP VLV control, see Searching with the LDAP VLV Control.