Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide
     Chapter 18 Functions

ldap_create_sort_control()

Creates a control that specifies the order in which you want search results returned.

This function implements an extension to the LDAP v3 protocol. Server-side sorting is an optional LDAP server feature; it may not be supported on all LDAP servers. Call this function when interacting with LDAP servers that support this LDAP v3 extension.

Syntax 

#include <ldap.h>
int ldap_create_sort_control( LDAP *ld, 
   LDAPsortkey **sortKeyList, const char ctl_iscritical, 
   LDAPControl **ctrlp );

Parameters

This function has the following parameters: 

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server. 

sortKeyList

Pointer to an array of LDAPsortkey structures that specify the attribute types or matching rules used for sorting and the order (ascending or descending) in which to sort the results. 

ctl_iscritical

Specifies whether or not the control is critical to the search operation. This field can have one of the following values:

ctrlp

Pointer to a pointer to an LDAPControl structure that will be created by this function. When you are done using this control, you should free it by calling the ldap_control_free() function.

Returns

One of the following values:

Description

The ldap_create_sort_control() function allows you to specify the order in which you want to receive data from the server. Calling this function creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions.

In order for the control to work, the LDAP server that you are connecting to must support the server control for sorting search results (OID 1.2.840.113556.1.4.473, or LDAP_CONTROL_SORTREQUEST as defined in ldap.h). See "Determining the Controls Supported By the Server" on page 288 for information on determining the controls supported by a server.

To specify the attributes to use for sorting the results, you can call ldap_create_sort_keylist() to create an array of LDAPsortkey structures and pass the array as the sortKeyList argument.

When you are done with the search, you should free the control and the array of LDAPsortkey structures by calling the ldap_control_free() function and the ldap_free_sort_keylist() function.

See Also

ldap_create_sort_keylist(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free().

Table of Contents | Previous | Next | Index

Last Updated: 10/01/98 17:06:23