| Directory Services |
The LDAPVLVInfo structure is used to set up the search parameters for a virtual list view (VLV) request control (LDAP_CONTROL_VLVREQUEST).
The LDAPVLVInfo structure may also be used by applications to manage the state data associated with a series of VLV client/server interactions.
typedef struct ldapvlvinfo {
int ldvlv_version;
unsigned long ldvlv_before_count;
unsigned long ldvlv_after_count;
unsigned long ldvlv_offset;
unsigned long ldvlv_count;
struct berval* ldvlv_attrvalue;
struct berval* ldvlv_context;
void* ldvlv_extradata;
} LDAPVLVInfo;
Si = Sc * (Ci / Cc)
where
Si is the actual list offset used by the server
Sc is the server's estimate for content count
Ci is the client's submitted offset
Cc is the client's submitted content count
If the client uses an offset value of one (1), it means that the target is the first entry in the list. If the client uses an offset value that equals ldvlv_count, then the item is the last entry in the list. The offset will equal zero (0) when ldvlv_count equals zero, which would be the last entry in the list.
Offsets are used only if the search is not based on an attribute value, so ldvlv_attrvalue must be NULL. This field corresponds to the offset element within the BER-encoded LDAP_CONTROL_VLVREQUEST control.
There are two methods for calculating the target of a VLV search: using an attribute value or using an offset. Different elements of this structure will be used depending on which type of search you choose. Both methods require that values be entered for the ldvlv_before_count and ldvlv_after_count members. Specify a list content count in ldvlv_count, or if you do not know this value, then use zero (0), so that the server will calculate it.
Searching with Attribute Values
To perform a value-based search, for example, if you wanted to search for Jeff Smith, and you know the attribute type for that value, then set the attribute type in the sk_attrtype member of the LDAPSortKey structure and the attribute value in ldvlv_attrvalue. The ldvlv_offset member is ignored for this type of search, so it is not necessary to set it.
For example, to perform a search using the letter J. To retrieve 20 results, set ldvlv_before_count to 9, ldvlv_after_count to 10 and ldvlv_attrvalue to J. The server finds the first entry in the list that is not less than J, such as Jeff Smith, and returns the nine preceding entries, the target entry, and the proceeding 10 entries. The server would return a ldvlv_count of 30000 and a ldvlv_offset of 4053 in the LDAP_CONTROL_VLVRESPONSE control; that is assuming that Jeff Smith is entry number 4053 on the list. The server may return few entries than requested before and/or after the target entry if there are insufficient entries in the list to satisfy the request. For example, if there were only two entries total before the first 'J' entry, the server could not return nine preceding entries.
Searching with Offsets
To use offsets for your search, set an offset in ldvlv_offset, and set ldvlv_attrvalue to NULL. Also set the attribute type in the sk_attrtype member of the LDAPSortKey, but this time, the target will be an offset within the list of entries for that attribute type, rather than a specific attribute value.
For example, to target the search 68 percent of the search results list. If the ldvlv_count is 30000, the 68 percent of 30000 is 20400. To retrieve 20 results, set ldvlv_before_count to 9, ldvlv_after_count to 10, ldvlv_count to 30000, ldvlv_offset to 20400 and send the request to the server. The server returns the preceding 20 entries in the list, plus the ldvlv_count of 30000 and a ldvlv_offset of 20400. Be aware that it is possible for the number of entries on the list to change between the client's estimation of the number of entries and the server processing the search, which in turn effects the offsets. In this case the target entry returned may not be exactly the target entry the client was expecting. Applications must be prepared to handle this uncertainty.
Note A sort control must accompany any VLV search request in order to specify the ordered list of entries against which the VLV search is performed. Servers are allowed to reject VLV searches performed against lists for which they do not have indices.
Client: Included in Windows XP.
Server: Included in Windows Server 2003.
Header: Declared in Winldap.h.
ldap_create_vlv_control, ldap_parse_vlv_control, LDAP_CONTROL_VLVREQUEST, LDAP_CONTROL_VLVRESPONSE, Searching with the LDAP VLV Control, ldap_search_ext, ldap_search_ext_s, ldap_create_sort_control, LDAPControl