ldap_parse_vlv_control function

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

Syntax

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:

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

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