LDAP_SORT

Edit online

Use the LDAP_SORT API or LDAP routine to request the entries that are sort and returned by the servers that match the filter that is specified on a search operation.

ldap_create_sort_keylist
ldap_free_sort_keylist
ldap_create_sort_control
ldap_parse_sort_control

Synopsis

#include ldap.h

int ldap_create_sort_keylist(
   LDAPsortkey       ***sortKeyList,
   const char        *sortString);  

int ldap_create_sort_control(
   LDAP              *ld, 
   LDAPsortkey       **sortKeyList,
   const char        isCritical,
   LDAPControl       **control)  

void ldap_free_sort_keylist(
   LDAPsortkey       **sortKeyList)

int ldap_parse_sort_control(
   LDAP              *ld,
   LDAPControl       **serverControls, 
   unsigned long     *sortRC,
   char              **attribute)

Input parameters

ld: Specifies the LDAP pointer that is returned by previous call to ldap_init(), ldap_ssl_init(), or ldap_open(). Must not be NULL.
sortString: String with one or more attributes to be used to sort entries that are returned by the server.
sortKeyList: Pointer to an array of LDAPsortkey structures, which represent attributes that the server uses to sort returned entries. Input when used for ldap_create_sort_control() and ldap_free_sort_keylist().
isCritical: Specifies the criticality of sort on the search. If the criticality of sort is FALSE, and the server finds a problem with the sort criteria, the search continues. However, the entries that are returned are not sorted. If the criticality of sort is TRUE, and the server finds a problem with the sort criteria, the search does not continue. No sorting is done, and no entries are returned. If the server does not find any problem with the sort criteria, the search and sort continues and entries are returned sorted.
serverControls: A list of LDAP server controls. For more information about server controls, see LDAP controls. These controls are returned to the client when you call the ldap_parse_result() function on the set of results that are returned by the server.

Output parameters

sortKeyList: Pointer to an array of LDAPsortkey structures, which represent attributes the server uses to sort returned entries. Output when used for ldap_create_sort_keylist().
control: A result parameter that is provided with an allocated array of one control for the sort function. The control must be freed by calling ldap_control_free().
sortRC: LDAP return code that is retrieved from the sort results control returned by the server.
attribute: Returned by the server, it is the name of the attribute in error.

Usage

These routines are used to sort the entries that are returned from the server after an LDAP search operation.

The ldap_create_sort_keylist() function builds a list of LDAPsortkey structures that are based on the list of attributes that are included in the incoming string. A sort key is made up of three possible values:

Name of attribute that is used to sort entries that are returned by the server
OID of a matching rule for that attribute
Whether the sort must be done in reverse order

The syntax of the attributes in the

sortString, [-]attribute
name[:<matching rule OID>]

, specifies whether there is a matching rule OID that must be used for the attribute, and whether the attribute must be sorted in reverse order. In the following sortString example, the search results are sorted first by surname and then by given name, with the given name that is sorted in reverse (descending order) as specified by the prefixed minus sign ( - ):

 sn -givenname

Thus, the syntax of the sort parameter is as follows:

 [-]attribute name[:matching rule OID]

where:

attribute name is the name of the attribute you want to sort by.
matching rule OID is the optional OID of a matching rule that you want to use for sorting.
the minus sign ( - ) indicates that the results must be sorted in reverse order.

The sortKeyList, output from the ldap_create_sort_keylist() function, can be used as input into the ldap_create_sort_control() function. The sortKeyList is an ordered array of LDAPsortkey structures such that the key with the highest precedence is at the front of the array. The control output form ldap_create_sort_control() function includes the criticality set based on the value of the isCritical flag. This control is added to the list of client controls that are sent to the server on the LDAP search request.

The ldap_free_sort_keylist() function cleans up all the memory that is used by the sort key list. This function must be called after the ldap_create_sort_control() function is completed.

When a sort results control is returned by the server, the ldap_parse_sort_control() function can be used to retrieve the values from the control. The function takes as input the server controls returned by the server, and returns the value of the sort control return code and possibly an attribute name if the return code is not LDAP_SUCCESS. No sort control is returned to the client if:

There was an error that parses the sort criteria for the search.
There were no entries that are returned for the search.

Server-side sorting of search results

Sorted Search Results provides sort capabilities for LDAP clients with limited or no sort functions. Sorted Search Results enables an LDAP client to receive sorted search results that are based on a list of criteria. Each criteria represents a sort key. The sort criteria includes attribute types, matching rules, or descending order. The server must use this criteria to sort search results before you return them. This criteria moves the responsibility of sorting from the client application to the server, where it might be done much more efficiently. For example, a client application might want to sort the list of employees at their Grand Cayman site by surname, common name, and telephone number. Instead of building the search list twice for sorting, the search list is built one time. It is then sorted, before it returns the results to the client application. The sort is done one time at the server and then again at the client when all the results are returned.

In the following sortString example, the search results are sorted first by surname (sn), then by given name (givenname), with the given name that is being sorted in reverse (descending) order as specified by the prefixed minus sign

(
- )

sn -givenname

The sortKeyList output from ldap_create_sort_keylist() can be used as input to ldap_create_sort_control(). The sortKeyList is an ordered array of LDAPsortkey structures such that the key with the highest precedence is at the front of the array. ldap_create_sort_control() outputs a LDAPControl structure which can be added to the list of client controls that are sent to the server on the LDAP search request. The LDAPControl structure that is returned by the ldap_create_sort_control() API can be used as input to ldap_search_ext() or ldap_search_ext_s(), which are used to make the actual search request.

Note: Server-side sorting is an optional extension of the LDAP v3 protocol, so the server you are bound to before the ldap_search_ext() or ldap_search_ext_s() call might not support this function.

Now that you created the server-side control, you can free the sortKeyList output from ldap_create_sort_keylist() by using ldap_free_sort_keylist().

Upon completion of the search request that you submitted by using ldap_search_ext() or ldap_search_ext_s(), the server returns an LDAP result message that includes a sort results control. The client application can parse this control by using ldap_parse_sort_control() which takes the returned server response controls (a null terminated array of pointers to LDAPControl structures) as input. ldap_parse_sort_control() outputs a return code that indicates whether the sort request was successful. If the sort was not successful, the name of the attribute in error might be output from ldap_parse_sort_control(). Use ldap_controls_free() to free the memory that is used by the client application to hold the server controls when you are done processing all controls that are returned by the server for this search request.

The server returns a successful return code of LDAP_SUCCESS in the sort response control (sortKeyResponseControl) in the search result (searchResultDone) message if the server supports sorting and can sort the search results by using the specified keys. If the search fails for any reason or there are no search results, then the server omits the sortKeyResponseControl from the searchResultsDone message.

If the server does not support sorting and the criticality that is specified on the sort control for the search request is TRUE, the server does not return any search results, and the sort response control return code is set to LDAP_UNAVAILABLE_CRITICAL_EXTENSION. If the server does not support the sorting and the criticality that is specified on the sort control for the search request is FALSE, the server returns all search results. The sort control is ignored.

If the server does support the sorting and the criticality that is specified on the sort control for the search request is TRUE, but for some reason the server cannot sort the search results, then the sort response control return code is set to LDAP_UNAVAILABLE_CRITICAL_EXTENSION and no search results are returned. If the server does support the sorting and the criticality that is specified on the sort control for the search request is FALSE, and for some reason the server cannot sort the search results, then the sort response control return code is set to the appropriate return code and all search results are returned unsorted.

The following return codes might be returned by the server in the sortKeyResponseControl of the searchResultDone message:

LDAP_SUCCESS - the results are sorted
LDAP_OPERATIONS_ERROR - server internal failure
LDAP_TIMELIMIT_EXCEEDED - time limit that is reached before the sorting was completed
LDAP_STRONG_AUTH_REQUIRED - refused to return sorted results by using insecure protocol
LDAP_ADMIN_LIMIT_EXCEEDED - too many matching entries for the server to sort
LDAP_NO_SUCH_ATTRIBUTE - unrecognized attribute type in sort key
LDAP_INAPPROPRIATE_MATCHING - unrecognized or inappropriate matching rule in sort key
LDAP_INSUFFICIENT_ACCESS - refused to return sorted results to this client
LDAP_BUSY - too busy to process
LDAP_UNWILLING_TO_PERFORM - unable to sort
LDAP_OTHER - unable to sort due to reasons other than the reasons specified earlier

There are other rules that must be considered when you request sort from the server. These rules are as follows:

The matching rule must be one that is valid for the sort attribute it applies to. The server returns LDAP_INAPPROPRIATE_MATCHING if it is not.
If the matching rule is omitted from a sort key, the ordering matching rule that is defined for use with this sort attribute must be used.
A server can restrict the number of keys that are supported for a sort control, such as supporting only one key. (A sort key list of at least one key must be supported).
A search result meets the search criteria but is missing a value for the sort key (sort attribute value is NULL). Then, this search result is considered a larger value than any other valid values for that key.

When sorted search is requested along with simple paged results, the sortKeyResponseControl is returned on every searchResultsDone message, not just the last one of the paged results requests. The sortKeyResponseControl might not be returned if there is an error that processes the paged results request or there are no search results to return. When sorted search is requested along with simple paged results, the server sends the search results sorted based on the entire search result set. It does not sort each page. For more information, see the section Simple paged results of search results in LDAP_PAGED_RESULTS.

When it chases referrals, the client application must send in a sorted search request to each of the referral servers. It is up to the application that uses the client services to decide whether to set the criticality as to the support of sorted search results. It is also to handle a lack of support of this control on referral servers as appropriate based on the application. Additionally, the LDAP server does not ensure that the referral server supports the sorted search control. Multiple lists might be returned to the client application, some of which are not sorted. It is the decision of the client application as to how best to present this information to the user. Possible solutions include:

Combine all referral results before it presents to the user
Show multiple lists and the corresponding referral server host name
Take no extra steps and show all results to the user as they are returned from the server

The client application must turn off referrals to get one truly sorted list. Otherwise, when it chases referrals with the sorted search control specified, unpredictable results can occur.

More information about the server side sorted search control, with control OID of 1.2.840.113556.1.4.473, can be found in RFC 2891 - LDAP Control Extension for Server Side Sorting of Search Results.

Errors

The sort routines return an LDAP error code if they encounter an error that parses the result. See LDAP_ERROR for a list of the LDAP error codes.

Notes

SortString, sortKeyList, controls, serverControls, and attribute must be freed by the caller.