Directory Services

LDAP_CONTROL_VLVRESPONSE

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 }
sequence data description
targetPosition Provides the list index position for the target entry.
contentCount Provides the server's 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 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 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 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

Client: Included in Windows XP.
Server: Included in Windows Server 2003.
Header: Declared in Winldap.h.

See Also

Data Structures, LDAPMessage, Using Controls