ldap_create_sort_controlW function (winldap.h)

The ldap_create_sort_control function is used to format a list of sort keys into a search control. Support for controls is available effective with LDAP 3, but whether the sort control is supported or not is dependent on the particular server.

Syntax

WINLDAPAPI ULONG LDAPAPI ldap_create_sort_controlW(
  [in]  PLDAP         ExternalHandle,
  [in]  PLDAPSortKeyW *SortKeys,
  [in]  UCHAR         IsCritical,
  [out] PLDAPControlW *Control
);

Parameters

[in] ExternalHandle

The session handle.

[in] SortKeys

Pointer to an array of LDAPSortKey structures. Each structure in the array specifies the name of an attribute to use as a sort key, the matching rule for that key, and whether the sort order is ascending or descending.

[in] IsCritical

Notifies the server whether this control is critical to the search. 0 ==> FALSE, !0 ==> TRUE.

[out] Control

Pointer to the newly created control.

Return value

This function returns WINLDAPAPI ULONG LDAPAPI.

Remarks

The ldap_create_sort_control function creates a basic sort control. Such a control is useful when the LDAP client has limited functionality and cannot sort results, yet needs them sorted.

The sort controls allow a server to return a result code for the sorting of the results that is independent of the result code returned for the search operation.

This function creates the control — it does not verify that the server supports it, and consequently, does not return LDAP_UNAVAILABLE_CRIT_EXTENSION if the server does not support the control. However, it can return other standard LDAP return values, such as LDAP_NO_MEMORY or LDAP_PARAM_ERROR.

To free the control when it is no longer required, call ldap_control_free.

Note

The winldap.h header defines ldap_create_sort_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

Functions

LDAPSortKey

LDAP_SERVER_SORT_OID

ldap_control_free