LDAP_CONTROL_VLVRESPONSE control code

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