This topic has not yet been rated - Rate this topic

ldap_parse_vlv_control function

Applies to: desktop apps only

The ldap_parse_vlv_control function is used to find and parse VLV search results.

Syntax

Copy

int ldap_parse_vlv_control(
  __in   LDAP *ld,
  __in   LDAPControl **ctrls,
  __out  unsigned long *target_posp,
  __out  unsigned long *list_countp,
  __out  struct berval **contextp,
  __out  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 numeric 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 value

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 issue occurs.

VLV uses the following LDAP return value 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. 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 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 must be freed at the end of the session by calling ber_bvfree.

For more information and a code example, see Example Code for Using LDAP VLV.

Requirements