ldap_parse_vlv_controlW function (winldap.h)

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

Syntax

WINLDAPAPI INT LDAPAPI ldap_parse_vlv_controlW(
  [in]  PLDAP         ExternalHandle,
  [in]  PLDAPControlW *Control,
  [out] PULONG        TargetPos,
  [out] PULONG        ListCount,
  [out] PBERVAL       *Context,
  [out] PINT          ErrCode
);

Parameters

[in] ExternalHandle

The LDAP session handle.

[in] Control

The address of a NULL-terminated array of LDAPControl structures, typically obtained by a call to ldap_parse_result.

[out] TargetPos

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.

[out] ListCount

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.

[out] Context

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.

[out] ErrCode

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:

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.

Note

The winldap.h header defines ldap_parse_vlv_control as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows Vista
Minimum supported server Windows Server 2008
Target Platform Windows
Header winldap.h
Library Wldap32.lib
DLL Wldap32.dll

See also

LDAPControl

LDAPVLVInfo

LDAP_CONTROL_VLVREQUEST

LDAP_CONTROL_VLVRESPONSE

Searching with the LDAP VLV Control

ldap_create_sort_control

ldap_create_vlv_control

ldap_search_ext

ldap_search_ext_s