LDAP_CONTROL_VLVRESPONSE control code

  • Article

The LDAP_CONTROL_VLVRESPONSE control is used to pass virtual list view (VLV) data from the server to the client.

This control cannot be sent; it can only be received. The LDAPControl structure will have its members set to the following:

PWCHAR ldctl_oid = LDAP_CONTROL_VLVRESPONSE;
struct berval ldctl_value;
BOOLEAN ldctl_iscritical = FALSE;

Members

ldctl_oid

LDAP_CONTROL_VLVRESPONSE defined as "2.16.840.1.113730.3.4.10".

ldctl_value

Returns a controlValue that is an OCTET STRING whose value is the BER-encoded sequence of parameters that the application uses to specify the LDAP_CONTROL_VLVRESPONSE control. The berval structure returns a pointer in bv_val to the sequence that contains the virtual list view data, and sets bv_len to the length of the sequence. For more information, see the Remarks section.

ldctl_iscritical

Returned as FALSE.

Remarks

The ldctl_value field is set to the following BER-encoded sequence.

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) },
  contextID              OCTET STRING OPTIONAL }

The following table lists the sequence fields.

Sequence data Description
targetPosition
 Provides the list index position for the target entry.
contentCount
 Provides the server estimate of the current number of entries in the list. Together with the targetPosition field, there is sufficient data for the client to update a list box slider position to match the newly retrieved entries and identify the target entry.
The value returned from this parameter should be used in a subsequent [LDAP_CONTROL_VLVREQUEST](ldap-control-vlvrequest.md) control.
virtualListViewResult
 Provides the codes commonly returned by the LDAP searchResponse operation. These codes have the same meanings as defined in LDAP 3, but they pertain specifically to the VLV operation. The following codes are used:
  • success
  • operationsError
  • unwillingToPerform
  • insufficientAccessRights
  • busy
  • timeLimitExceeded
  • adminLimitExceeded
  • sortControlMissing
  • offsetRangeError
  • other
For example, the server could exceed an administration limit while processing a SearchRequest with a [LDAP_CONTROL_VLVREQUEST](ldap-control-vlvrequest.md) control. However, the same administration limit would not be exceeded if the same SearchRequest were submitted by the client without the LDAP_CONTROL_VLVREQUEST control. In this case, the client can determine that an administration limit has been exceeded while servicing the VLV request, and it can resubmit the SearchRequest without the LDAP_CONTROL_VLVREQUEST control.
The insufficientAccessRights code means that the server denied the client permission to perform the VLV operation. If the server determines that the results of the search exceed the range provided by the 32-bit offset values, it must return offsetRangeError.
contextID
 Provides a server-defined octet string used to identify this search operation when sending additional requests to the server. If present, the contents of the contextID field should be returned to the server by a client in a subsequent [LDAP_CONTROL_VLVREQUEST](ldap-control-vlvrequest.md) control that pertains to the same list on the same server. Do not pass it back on just any future VLVREQUEST. If the client uses the contextID that the server passed back, it will improve the response time on the next query to the server.

Requirements
Minimum supported client
 Windows Vista
Minimum supported server
 Windows Server 2008
Header
Winldap.h

See also

Data Structures

LDAPMessage

Using Controls