Overview#

The virtual list view (VLV) is a supportedControl that can be attached to a searchRequest to use a server-side sorting control.

Virtual List View Control may be combined with the simple paged results control the search Request also include the server-side sort control to ensure that the results are consistently sorted across requests.

The VLV control is defined in draft-ietf-ldapext-ldapv3-vlv.

As far as we can determine this is NOT an approved standard.

The request control has an OID of 2.16.840.1.113730.3.4.9 and the value is encoded as follows:

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

The response control has an OID of 2.16.840.1.113730.3.4.10 and the value is encoded as:

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

Virtual List View Control Example#

To Search Using the Virtual List View Control The sort order option (-S) must be used with the Virtual List View control. This example uses the Virtual List View Control options to specify the following:

• Before=0*. Specifies that 0 entries before the target should be displayed.
• After=2*. Specifies that 2 entries after the target should be displayed.
• Index=1*. Specifies that the offset of the target entry within the result set be returned.
• Count=0*. Specifies that target entry at the index position be returned, which is the first entry.

Thus, the server returns the first entry plus two entries after the target sorted in ascending order by the givenName attribute.

This example is from the OpenDS LDAPSEARCH utility (Other LDAP vendors tools may vary)

ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w bindPassword  -b dc=example,dc=com --searchScope sub --sortOrder givenName  --virtualListView "0:2:1:0" "(objectclass=*)"

The same only for OpenLDAP (at least used to work)

ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w bindPassword  -b dc=example,dc=com --searchScope sub -S givenName -x -G "0:2:1:0" "(objectclass=*) givenName"

To find the first two entries where givenName starts with "j" (OpenLDAP)

• Before=0*. Specifies that 0 entries before the target should be displayed.
• After=2*. Specifies that 2 entries after the target should be displayed.
• "j" for entries where givenName begins with "j"

ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w bindPassword  -b dc=example,dc=com --searchScope sub -S givenName -x -G "0:4:j" "(objectclass=*) givenName"

Virtual List View Control and eDirectory#

eDirectory LDAP Virtual List View And Server Side Sort Controls

Virtual List View Control Microsoft Active Directory#

Virtual List View Control seems to have an issue when MaxTempTableSize is smaller than the total number of Objects. The Virtual List View Control may fail with a LDAP Result Codes of Unavailable Critical Extension similar to:

LdapException: (12) Unavailable Critical Extension
LdapException: Server Message: 000020EF: SvcErr: DSID-03140552, problem 5010 (UNAVAIL_EXTENSION), data 0

Error code: 53

More Information#

There might be more information for this subject on one of the following:

• 2.16.840.1.113730.3.4.9
• EDirectoryLDAPVirtualListViewAndServerSideSortControls
• Glossary Of LDAP And Directory Terminology
• LDAP Extensions and Controls Listing
• LDAPControlsList
• MaxTempTableSize
• Search Using the Virtual List View Control
• SupportedControl
• VLV
• X-SEARCH-FLAGS

---

• [#1] - Virtual List View Active Directory search LdapException: Unavailable Critical Extension - based on information obtained 2020-03-17