3.1.1.3.4.1.17 LDAP_CONTROL_VLVREQUEST and LDAP_CONTROL_VLVRESPONSE

The LDAP_CONTROL_VLVREQUEST control is used with an LDAP search operation to retrieve a subset of the objects that satisfy the search request. This control permits the client to specify a particular object (the "target object") in a sorted set of search results, and to request that the server return a specified number of objects before and after the target object, in addition to the target object itself. "Before" and "after" the target object are relative to the sort order of the search result set. The server will not return objects whose attribute value, used as the sort key, is absent. This control can only be used if the LDAP_SERVER_SORT_OID (section 3.1.1.3.4.1.13) control is also specified.

When sending this control to the DC, the controlValue field is set to the BER encoding of the following ASN.1 structure (maxInt is defined in [RFC2251] section 4.1.1):

 VLVRequestValue ::= SEQUENCE {
   beforeCount        INTEGER (0..maxInt),
   afterCount         INTEGER (0..maxInt),
   CHOICE {
     byoffset           [0] SEQUENCE {
                            offset       INTEGER (0 .. maxInt),
                            contentCount INTEGER (0 .. maxInt)
                            },
     greaterThanOrEqual [1] AssertionValue
   },
   contextID          OCTET STRING OPTIONAL
 }

where beforeCount indicates how many objects before the target object are to be included in the search results, and afterCount indicates how many objects after the target object are to be included in the search results.

byoffset and greaterThanOrEqual provide two mutually exclusive ways of specifying the target object. These will now be discussed in turn.

First, the target object can be specified by its position relative to the first object in the sorted set of objects that satisfy the search request, in which case the byoffset choice is used. In this case, contentCount contains the client's estimation of the total number of objects that satisfy the search criteria. If the client specifies 0 for contentCount, it is as if the client had specified a number identical to the server's estimate of the total number of objects that satisfy the search criteria—the quantity serverContentCount below. offset is used with contentCount to specify the position (relative to the first object in the sorted set of search results) of the object to use as the target object according to the following formula:

p = serverContentCount * (offset / contentCount)

where serverContentCount is the DC's estimate of the total number of objects that satisfy the search criteria. The object located at position p in the sorted list of search results is used as the target object.

A value of offset equal to 1 means that the target object is the first object in the search result set, while a value of offset equal to contentCount means the target object is the last object in the search result set. The offset value cannot equal 0 unless contentCount also equals 0. If the client specified 0 for contentCount, then p = offset in the preceding formula, so the target object is offset-1 objects beyond the first object in the search result set, unless both offset and contentCount are equal to 0, in which case the previous rule applies.

The second means of specifying the target object is by the greaterThanOrEqual choice, instead of the byoffset choice. In this case, greaterThanOrEqual is an AssertionValue as defined in [RFC2251] section 4.1.7. The target object is the first object in the sorted result set for which the value of the attribute on which it is sorted (that is, the attribute specified by attributeType in the LDAP_SERVER_SORT_OID control) is greater than or equal to the value specified by greaterThanOrEqual. However, if the sort order is reversed (by specifying that the reverseOrder field of the LDAP_SERVER_SORT_OID control is TRUE), then the target object is the first object for which the sort attribute value is less than or equal to the greaterThanOrEqual value.

If the contextID field is present, it is the opaque value returned by the DC as the contextIDServer field of the LDAP_CONTROL_VLVRESPONSE control that was returned with the search response to the previous search over the same "list" as this search. A "list" is a sorted set of search results, defined by a search request value sent to a particular DC over a particular LDAP connection. The client omits this field if this is the first search request that included the LDAP_CONTROL_VLVREQUEST control for the "list", or if the client did not retain the contextIDServer field of the previous LDAP_CONTROL_VLVRESPONSE for the "list". The presence or absence of the contextID field in the request only affects performance. The contextID is valid only on the DC that returned it. If an invalid contextID is present, then the LDAP_CONTROL_VLVREQUEST control is ignored.

When the server receives a search request with the LDAP_CONTROL_VLVREQUEST control attached to it, it includes a response control in the search response. The controlType field of the returned Control structure is set to the OID of the LDAP_CONTROL_VLVRESPONSE control, and the controlValue is the BER encoding of the following ASN.1 structure.

 VLVResponseValue ::= SEQUENCE {
     targetPosition        INTEGER (0 .. maxInt),
     contentCount          INTEGER (0 .. maxInt),
     virtualListViewResult ENUMERATED {
                               success                  (0),
                               operationsError          (1),
                               unwillingToPerform       (53),
                               insufficientAccessRights (50),
                               busy                     (51),
                               timeLimitExceeded        (3),
                               adminLimitExceeded       (11),
                               sortControlMissing       (60),
                               offsetRangeError         (61),
                               other                    (80)
                               },
     contextIDServer       OCTET STRING OPTIONAL
 }

where targetPosition is the position of the target object relative to the beginning of the sorted set of search results, contentCount is the server's estimate of the total number of objects that satisfy the search request, contextIDServer is the opaque value described in the specification of the contextID field earlier in this section, and virtualListViewResult is an LDAP error code that indicates the success or failure of the DC in processing the LDAP_CONTROL_VLVREQUEST control. These codes have the same meanings as defined for LDAP in [RFC2251], but they pertain specifically to the processing of the control. Error codes sortControlMissing and offsetRangeError are not defined in [RFC2251]. In the Active Directory implementation of virtual list view (VLV), virtualListViewResult is set to error code sortControlMissing if the LDAP_SERVER_SORT_OID control is not specified in conjunction with the LDAP_CONTROL_VLVREQUEST control. It is set to error code offsetRangeError if contentCount is not equal to 0 but offset is equal to 0.

Notes:

  • The Active Directory implementation of VLV is based on that described in [VLVDRAFT]. Although implementers can consult that document as an informative reference, the preceding description documents the protocol as implemented by Active Directory. No claim is made with regard to Active Directory's conformance or nonconformance with the protocol as specified in [VLVDRAFT].

  • Active Directory support for VLV is specified in section 3.1.1.3.4.1 (see LDAP_CONTROL_VLVREQUEST and LDAP_CONTROL_VLVRESPONSE). The following information applies to the Active Directory implementation of VLV through Windows Server 2012 R2 operating system without [MSKB-3106637] installed, or through Windows Server 2012 operating system with [MSKB-3106637] installed:

    If an LDAP search has the LDAP_CONTROL_VLVREQUEST attached, a desired target object is specified using the greaterThanOrEqual choice, and the attribute specified in the sort control is of the 2.5.5.11 time syntax (section 3.1.1.2.2.2), a random object is returned, not an object that satisfies the greaterThanOrEqual value.