Directory Services

ldap_parse_vlv_control

The ldap_parse_vlv_control function is used to look for and parse the VLV search results.

int ldap_parse_vlv_control(
  LDAP* ld,
  LDAPControl** ctrls,
  unsigned long* target_posp,
  unsigned long* list_countp,
  struct berval** contextp,
  int* errcodep
);

Parameters

ld
[in] The LDAP session handle.
ctrls
[in] The address of a NULL-terminated array of LDAPControl structures, typically obtained by a call to ldap_parse_result.
target_posp
[out] The numerical position of the target entry in the result set list, as provided by the targetPosition element of the BER-encoded response control (LDAP_CONTROL_VLVRESPONSE). If this parameter is NULL, the target position is not returned.
list_countp
[out] The server estimate of the number of entries in the list as provided by the contentCount element of the BER-encoded response control (LDAP_CONTROL_VLVRESPONSE). If this parameter is NULL, the size is not returned.
contextp
[out] The server-generated context identifier. If the server does not return a context identifier, this parameter will be set to NULL. If NULL is passed for contextp, the context identifier is not returned.
errcodep
[out] The VLV result code, as provided by the virtualListViewResult element of the BER-encoded response control (LDAP_CONTROL_VLVRESPONSE). If this parameter is NULL, the result code is not returned.

Return Values

This function returns an LDAP error code that indicates whether a VLV result control was found and parsed successfully. LDAP_SUCCESS is returned if all goes well, LDAP_CONTROL_MISSING is returned if the ctrls array does not include a response control (LDAP_CONTROL_VLVRESPONSE), and another LDAP error code is returned if a parsing error or other problem occurs.

VLV uses the following LDAP result codes:

LDAP_OPERATIONS_ERROR

LDAP_UNWILLING_TO_PERFORM

LDAP_INSUFFICIENT_ACCESS

LDAP_BUSY

LDAP_TIMELIMIT_EXCEEDED

LDAP_ADMINLIMIT_EXCEEDED

LDAP_OTHER

In addition, the following two codes have been added to support VLV:

Return Code Description
LDAP_SORT_CONTROL_MISSING The VLV control must be accompanied by a sort control for it to work. If not, the server returns this error.
LDAP_OFFSET_RANGE_ERROR The server returns this error when you have set up a search using offsets, but you have set the offset member of the LDAPVLVInfo structure to zero (0).

Remarks

This control parses the search results that are returned by the server in the response control (LDAP_CONTROL_VLVRESPONSE). A context identifier is passed from the server to the client to identify the control, which you will need to free at the end of the session by calling ber_bvfree.

For a code sample for this function, see Example Code for Using LDAP VLV.

Requirements

Client: Included in Windows XP.
Server: Included in Windows Server 2003.
Unicode: Implemented as Unicode and ANSI versions.
Header: Declared in Winldap.h.
Library: Use Wldap32.lib.

See Also

ldap_create_vlv_control, LDAP_CONTROL_VLVREQUEST, LDAP_CONTROL_VLVRESPONSE, LDAPVLVInfo, Searching with the LDAP VLV Control, ldap_search_ext, ldap_search_ext_s, ldap_create_sort_control, LDAPControl