You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

Mozilla LDAP C SDK Programmer's Guide

Chapter 17 - Data Types and Structures

This chapter describes the data structures and data types used by functions in the LDAP API. The chapter documents the following data structures and data types:

berval

berval represents binary data that is encoded using simplified Basic Encoding Rules (BER). The data and size of the data are included in a berval structure.

berval is defined as follows:

struct berval {
  unsigned long bv_len;
  char *bv_val;
};

The fields in this structure are described below:

bv_len
The length of the data.
bv_val
The binary data.

Use a berval structure when working with attributes that contain binary data (such as a JPEG or audio file).

BerElement

BerElement represents data encoded using the Basic Encoding Rules (BER). BerElement is not completely exposed in ldap.h because the fields within the structure are not intended to be accessible to clients.

Calling the ldap_first_attribute() function allocates a BerElement structure in memory. You use this structure to keep track of the current attribute. When you are done reading attributes in an entry, you need to free the BerElement structure from memory by calling the ldap_ber_free() function.

FriendlyMap

FriendlyMap represents the mapping between a list of "unfriendly names" and "friendly names". For example, you can represent the list of two-letter state codes (cryptic, "unfriendly names") and corresponding state names (easy to understand, "friendly names") in a FriendlyMap structure.

FriendlyMap is not completely defined in ldap.h because the fields within the structure are not intended to be accessible to clients.

Calling the ldap_friendly_name() routine allocates a FriendlyMap structure and reads a list of "unfriendly names" and "friendly names" from a file.

LDAP

LDAP is a type of structure representing the connection with the LDAP server. LDAP is not completely defined in ldap.h because the fields within the structure are not intended to be accessible to clients.

When you call functions that perform LDAP operations on an LDAP server (for example, when you call ldap_search_ext() to search the directory or ldap_modify_ext() to update an entry in the directory), you need to pass a pointer to an LDAP structure as a parameter to the function.

To create, manipulate, and free an LDAP structure, call the following functions:

LDAP_CMP_CALLBACK

LDAP_CMP_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and specify it when calling the ldap_sort_entries() or ldap_multisort_entries() function, your function will be called by your LDAP client. The client will call your function to sort a specified set of entries.

The prototype specified by this data type is:

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_CMP_CALLBACK)(const char*, const char*);

For information on the arguments, return values, and purpose of this function, see ldap_sort_entries() and ldap_multisort_entries().

LDAPControl

LDAPControl represents a client or server control associated with an LDAP operation. Controls are part of the LDAPv3 protocol. You can use a control to extend the functionality of an LDAP operation.

There are two basic types of controls described in the LDAPv3 protocol:

  • Server controls are controls that are sent from the client to the server along with an LDAP request. (In some cases, a server can include a control in the response it sends back to the client.)

    For example, you can include a server control in a search request to specify that you want the server to sort the search results before sending them back.
  • Client controls are controls that can extend the client but that are never sent to the server. As a general example, you might be able to pass a client control to an LDAP API function, which might parse the control and use the data that you've specified in the control.

    Note that the Mozilla LDAP C SDK does not currently support any client controls.

LDAPControl is defined as follows:

typedef struct ldapcontrol {
  char *ldctl_oid;
  struct berval ldctl_value;
  char ldctl_iscritical;
} LDAPControl;

The fields in this structure are described below:

ldctl_oid
Object identifier (OID) of the control.
ldctl_value
berval structure containing data associated with the control.

If you want to specify a zero-length value, set ldctl_value.bv_len to 0 and ldctl_value.bv_val to a zero-length string.

To indicate that no data is associated with the control, set ldctl_value.bv_val to NULL.
ldctl_iscritical
Specifies whether or not the control is critical to the operation. This field can have one of the following values:
  • A non-zero value specifies that the control is critical to the operation.
  • 0 specifies that the control is not critical to the operation.

For more information on LDAP controls, see Chapter 14 - Working with LDAP Controls.

LDAP_DNSFN_GETHOSTBYADDR

LDAP_DNSFN_GETHOSTBYADDR specifies the prototype for a callback function. This callback function should be equivalent to the gethostbyaddr_r() function that is available on some UNIX platforms.

If you define a function with this prototype and set it in the ldap_dns_fns structure, your function will be called by the LDAP C SDK on behalf of your LDAP client if it needs to get the hostname of the LDAP server to which it is connected.

The prototype specified by this data type is:

typedef LDAPHostEnt * (LDAP_C LDAP_CALLBACK
LDAP_DNSFN_GETHOSTBYADDR)( const char *addr, int length, int type,
  LDAPHostEnt *result, char *buffer, int buflen, int *statusp,
  void *extradata );

LDAP_DNSFN_GETHOSTBYNAME

LDAP_DNSFN_GETHOSTBYNAME specifies the prototype for a callback function. This callback function should be equivalent to the gethostbyname_r() function that is available on some UNIX platforms.

If you define a function with this prototype and set it in the ldap_dns_fns structure, your function will be called by the LDAP SDK on behalf of your LDAP client to get the host entry for the LDAP server when connecting to the server.

The prototype specified by this data type is: 

typedef LDAPHostEnt * (LDAP_C LDAP_CALLBACK
LDAP_DNSFN_GETHOSTBYADDR)( const char *addr, int length, int type,
  LDAPHostEnt *result, char *buffer, int buflen, int *statusp,
  void *extradata );

ldap_dns_fns

ldap_dns_fns contains a set of pointers to DNS functions (equivalents to the gethostbyname_r() and gethostbyaddr_r() functions that are available on some UNIX platforms.)

You can use this if you want the LDAP C SDK to call these functions when looking up the hostname or IP address for the LDAP server. For example, you could use this to call versions of the DNS functions that are safe for use in a multi-threaded application.

After you set the fields in this structure, you can register the functions in this structure for use by the client by calling the ldap_set_option() function and set the LDAP_OPT_DNS_FN_PTRS option to this structure.

ldap_dns_fns is defined as follows: 

struct ldap_dns_fns {
  void *lddnsfn_extradata;
  int lddnsfn_bufsize;
  LDAP_DNSFN_GETHOSTBYNAME *lddnsfn_gethostbyname;
  LDAP_DNSFN_GETHOSTBYADDR *lddnsfn_gethostbyaddr;
};

The fields in this structure are described below:

lddnsfn_extradata
Value passed in the extradata argument of the LDAP_DNSFN_GETHOSTBYADDR and LDAP_DNSFN_GETHOSTBYADDR function calls.
lddnsfn_bufsize
Specifies the size of the buffer that you want passed to your DNS callback function. Your LDAP client passes this value as the buflen argument of the LDAP_DNSFN_GETHOSTBYADDR and LDAP_DNSFN_GETHOSTBYADDR function calls.
lddnsfn_gethostbyname
Function pointer for getting the host entry for the LDAP server. This function is called by the client when connecting to the server if the function pointer is not NULL. The function must have the prototype specified by LDAP_DNSFN_GETHOSTBYNAME. If NULL, the standard built-in OS routine is used.
lddnsfn_gethostbyaddr

Function pointer for getting the host name of the LDAP server. This function is called by the client when needed if the function pointer is not NULL.

The function must have the prototype specified by LDAP_DNSFN_GETHOSTBYADDR. If NULL, the standard built-in OS routine is used.

ldap_extra_thread_fns

The ldap_extra_thread_fns structure contains a set of pointers to additional functions that you want to use when write a multithreaded client. Your client calls these functions when getting results from the LDAP structure.

Note that the LDAP C SDK ignores all the elements in this structure except for the ltf_threadid_fn function. Calling ltf_threadid_fn will, in some cases, enhance the performance of a multithreaded program.

After you set the fields in this structure, you can register the functions in this structure for use by the client by calling the ldap_set_option() function and set the LDAP_OPT_EXTRA_THREAD_FN_PTRS option to this structure.

The ldap_extra_thread_fns structure is defined as follows: 

struct ldap_extra_thread_fns {
  LDAP_TF_MUTEX_TRYLOCK_CALLBACK  *ltf_mutex_trylock;
  LDAP_TF_SEMA_ALLOC_CALLBACK     *ltf_sema_alloc;
  LDAP_TF_SEMA_FREE_CALLBACK      *ltf_sema_free;
  LDAP_TF_SEMA_WAIT_CALLBACK      *ltf_sema_wait;
  LDAP_TF_SEMA_POST_CALLBACK      *ltf_sema_post;
  LDAP_TF_THREADID_CALLBACK       *ltf_threadid_fn;
};

The fields in this structure are described below:

ltf_mutex_trylock
Function pointer for attempting to lock a mutex. This function is called by the client when needed if the function pointer is not NULL. The function must have the prototype specified by LDAP_TF_MUTEX_TRYLOCK_CALLBACK.
ltf_sema_alloc
Function pointer for allocating a semaphore. This function is called by the client when needed if the function pointer is not NULL. The function must have the prototype specified by LDAP_TF_SEMA_ALLOC_CALLBACK.
ltf_sema_free
Function pointer for freeing a semaphore. This function is called by the client when needed if the function pointer is not NULL. The function must have the prototype specified by LDAP_TF_SEMA_FREE_CALLBACK.
ltf_sema_wait
Function pointer for waiting for the value of a semaphore to be greater than 0. This function is called by the client when needed if the function pointer is not NULL. The function must have the prototype specified by LDAP_TF_SEMA_WAIT_CALLBACK.
ltf_sema_post

Function pointer for incrementing the value of a semaphore. This function is called by the client when needed if the function pointer is not NULL.

The function must have the prototype specified by LDAP_TF_SEMA_POST_CALLBACK.

ltf_threadid_fn

Function pointer that is called to retieve the unique identifier for the calling thread. If this is NULL, it is not used. An example of a similar function in the POSIX threads standard is pthread_self().

The function must have the prototype specified by LDAP_TF_THREADID_CALLBACK.

For an example of setting up the ldap_extra_thread_fns structure, see Chapter 16 - Writing Multithreaded Clients.

LDAPFiltDesc

LDAPFiltDesc is a type of structure that is returned when you call the ldap_init_getfilter() routine to load a filter configuration file. LDAPFiltDesc is not completely defined in ldap.h because the fields within the structure are not intended to be accessible to clients.

After calling the ldap_init_getfilter() routine, use the pointer to the returned LDAPFiltDesc structure in subsequent calls to get information about filters in the filter configuration file.

LDAPFiltInfo

LDAPFiltInfo represents information about a filter in the filter configuration file. When you call the ldap_getfirstfilter() or ldap_getnextfilter() routines to get a filter from the filter configuration file, the routines return a pointer to an LDAPFiltInfo structure containing the information about the filter.

LDAPFiltInfo is defined as follows: 

typedef struct ldap_filt_info {
  char *lfi_filter;
  char *lfi_desc;
  int lfi_scope;
  int lfi_isexact;
  struct ldap_filt_info *lfi_next;
} LDAPFiltInfo;

The fields in this structure are described below:

lfi_filter
The filter (for example, (cn=d*)).
lfi_desc
Description of the filter (the fifth field in the filter configuration file).
lfi_scope

The scope of the filter (the sixth field in the filter configuration file), which can be one of the following values:

  • LDAP_SCOPE_BASE specifies that the search will be restricted to the current distinguished name.
  • LDAP_SCOPE_ONELEVEL specifies that the search will be restricted to the entries at the level beneath the current distinguished name.
  • LDAP_SCOPE_SUBTREE specifies that the search will encompass entries at all levels beneath the current distinguished name.

If the scope of the filter is not specified in the filter configuration file, the scope is LDAP_SCOPE_SUBTREE by default.

lfi_isexact

Specifies whether or not the filter is an exact filter (an exact filter contains no wildcards and does not match words that sound alike):

  • 0 specifies that the filter is not an exact filter.
  • 1 specifies that the filter is an exact filter.
lfi_next
Pointer to the LDAPFiltInfo structure representing the next filter in the filter list.

The following section of code prints out information about a filter: 

LDAPFiltInfo *lfip;
/* Print out the filter */
printf( "Filter:\t%s\n", lfdp->lfd_filter );
printf( "Description:\t%s\n", lfdp->lfd_desc );

For example, in the filter configuration file, if the first filter that applies to the value "@" is:

"@" " " "(mail=%v)" "email address is" "onelevel"

The code prints out: 

Filter: (mail=@)
 Description: email address is

LDAPHostEnt

LDAPHostEnt represents an entry for a host found by a domain name server. This type is similar to the hostent structure returned by functions such as gethostbyname_r() on UNIX.

If you are writing your own DNS functions for use by the client, your functions should return the host entry in this type of structure. See the documentation on LDAP_DNSFN_GETHOSTBYADDR and LDAP_DNSFN_GETHOSTBYNAME for details.

The fields in this structure should point to addresses within the buffer that is passed to the DNS callback (referenced in the LDAP callback function). This buffer contains the host data. The pointers in the hostent structure returned by the function point to the data in this buffer.

LDAPHostEnt is defined as follows: 

typedef struct LDAPHostEnt {
  char *ldaphe_name;
  char **ldaphe_aliases;
  int ldaphe_addrtype;
  int ldaphe_length;
  char **ldaphe_addr_list;
} LDAPHostEnt;

The fields in this structure are described below:

ldaphe_name
Canonical name of the host.
ldaphe_aliases
List of aliases for this host.
ldaphe_addrtype
Address type of the host.
ldaphe_length
Length of the address.
ldaphe_addr_list
List of addresses for this host (as returned by the name server).

LDAP_IOF_CLOSE_CALLBACK

LDAP_IOF_CLOSE_CONNECT_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_io_fns structure, your function will be called by your LDAP client.

This callback function is equivalent to the standard close() system call.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_CLOSE_CALLBACK )( LBER_SOCKET );

LDAP_IOF_CONNECT_CALLBACK

LDAP_IOF_CONNECT_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_io_fns structure, your function will be called by your LDAP client.

This callback function is equivalent to the standard connect() network I/O function.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_CONNECT_CALLBACK )( LBER_SOCKET,
  struct sockaddr *, int );

LDAP_IOF_IOCTL_CALLBACK

LDAP_IOF_IOCTL_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_io_fns structure, your function will be called by your LDAP client.

This callback function is equivalent to the standard ioctl() system call.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_IOCTL_CALLBACK)( LBER_SOCKET, int, ... );

LDAP_IOF_READ_CALLBACK

LDAP_IOF_READ_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_io_fns structure, your function will be called by your LDAP client.

This callback function is equivalent to the standard read() I/O function.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_READ_CALLBACK)( LBER_SOCKET, void *, int );

LDAP_IOF_SELECT_CALLBACK

LDAP_IOF_SELECT_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_io_fns structure, your function will be called by your LDAP client.

This callback function is equivalent to the standard select() I/O function.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
LDAP_IOF_SELECT_CALLBACK)( int, fd_set *, fd_set *,
  fd_set *, struct timeval * );

LDAP_IOF_SOCKET_CALLBACK

LDAP_IOF_SOCKET_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_io_fns structure, your function will be called by your LDAP client.

This callback function is equivalent to the standard socket() network I/O function.

The prototype specified by this data type is: 

typedef LBER_SOCKET (LDAP_C LDAP_CALLBACK
  LDAP_IOF_SOCKET_CALLBACK)( int, int, int );

LDAP_IOF_SSL_ENABLE_CALLBACK

LDAP_IOF_SSL_ENABLE_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_io_fns structure, your function will be called by your LDAP client.

This callback function is equivalent to the ssl_enable() function.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_SSL_ENABLE_CALLBACK )( LBER_SOCKET );

LDAP_IOF_WRITE_CALLBACK

LDAP_IOF_WRITE_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_io_fns structure, your function will be called by your LDAP client.

This callback function is equivalent to the standard write() I/O function.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK LDAP_IOF_WRITE_CALLBACK)
  ( LBER_SOCKET, const void *, int );

ldap_io_fns

The ldap_io_fns structure contains a set of pointers to input/output functions that you want used with the Directory Server API. You need to set up this structure if you want to connect to the LDAP server using a secure sockets layer (SSL).

The ldap_io_fns structure is defined as follows: 

struct ldap_io_fns {
  LDAP_IOF_READ_CALLBACK *liof_read;
  LDAP_IOF_WRITE_CALLBACK *liof_write;
  LDAP_IOF_SELECT_CALLBACK *liof_select;
  LDAP_IOF_SOCKET_CALLBACK *liof_socket;
  LDAP_IOF_IOCTL_CALLBACK *liof_ioctl;
  LDAP_IOF_CONNECT_CALLBACK *liof_connect;
  LDAP_IOF_CLOSE_CALLBACK *liof_close;
  LDAP_IOF_SSL_ENABLE_CALLBACK *liof_ssl_enable;
};

The fields in this structure are described below:

liof_read
Function pointer to the equivalent of the standard read() I/O function. The function must have the prototype specified by LDAP_IOF_READ_CALLBACK.
liof_write
Function pointer to the equivalent of the standard write() I/O function. The function must have the prototype specified by LDAP_IOF_WRITE_CALLBACK.
liof_select
Function pointer to the equivalent of the standard select() I/O function. The function must have the prototype specified by LDAP_IOF_SELECT_CALLBACK.
liof_socket
Function pointer to the equivalent of the standard socket() network I/O function. The function must have the prototype specified by LDAP_IOF_SOCKET_CALLBACK.
liof_ioctl
Function pointer to the equivalent of the standard ioctl() system call. The function must have the prototype specified by LDAP_IOF_IOCTL_CALLBACK.
liof_connect
Function pointer to the equivalent of the standard connect() network I/O function. The function must have the prototype specified by LDAP_IOF_CONNECT_CALLBACK.
liof_close
Function pointer to the equivalent of the standard close() system call. The function must have the prototype specified by LDAP_IOF_CLOSE_CALLBACK.
liof_ssl_enable
Function pointer to the equivalent of the ssl_enable() function. The function must have the prototype specified by LDAP_IOF_SSL_ENABLE_CALLBACK.

LDAPMemCache

LDAPMemCache is a type of structure representing an in-memory, client-side cache.

You can create a cache and specify the following information:

  • The maximum size of the cache.
  • The maximum amount of time to keep an item in the cache.
  • A set of base DNs for the search requests that you want to cache (optional).
  • A set of functions that you want used to ensure the thread-safety of the cache.

To use a cache, you need to associate it with a connection handle (and LDAP structure). Before a search request is sent to the server, the cache is checked to determine if the same request was made before. If an earlier request was cached, the search results are retrieved from the cache.

Note that the cache uses the search criteria as the key to cached items. Search requests with different criteria are cached as separate items.

For example, suppose you send a search request specifying that you just want to retrieve the uid attribute. Your client caches the results of that search. If you send a similar search request specifying that you want to retrieve all attributes instead of just the uid, the results cached from the previous search are not used.

The cache uses a combination of the following information as the key to a cached item:

  • The hostname and port number of the LDAP server that you are searching.
  • The DN to which you are currently authenticated.
  • From the search criteria, the base DN, scope, filter, attributes to be returned, and an indication of whether to return attribute types only or attribute types and values.

Use the following functions to work with the cache:

LDAPMessage

LDAPMessage is a type of structure representing the results of an LDAP operation, a chain of search results, an entry in the search results, or a search reference in the search results. LDAPMessage is not completely defined in ldap.h because the fields within the structure are not intended to be directly accessible to clients.

Calling the ldap_search_ext_s() or ldap_search_ext() followed by ldap_result() function creates an LDAPMessage structure to represent the chain of results of a search. Calling the ldap_first_entry() or ldap_next_entry() function creates an LDAPMessage structure to represent an entry in the search results. Calling ldap_first_reference() or ldap_next_reference() creates an LDAPMessage structure to represent a search reference in the search results.

To free the LDAPMessage structure, call the ldap_msgfree() routine.

LDAPMod

LDAPMod is a type of structure that you use to specify changes to an attribute in an directory entry. Before you call the ldap_add_ext(), ldap_add_ext_s(), ldap_modify_ext(), or ldap_modify_ext_s() routines to add or modify an entry in the directory, you need to fill LDAPMod structures with the attribute values that you intend to add or change.

LDAPMod is defined as follows: 

typedef struct ldapmod {
  int mod_op;
  char *mod_type;
  union {
    char **modv_strvals;
    struct berval **modv_bvals;
  } mod_vals;
#define mod_values mod_vals.modv_strvals
#define mod_bvalues mod_vals.modv_bvals
} LDAPMod;

The fields in this structure are described below:

mod_op

The operation to be performed on the attribute and the type of data specified as the attribute values. This field can have one of the following values:

  • LDAP_MOD_ADD adds a value to the attribute.
  • LDAP_MOD_DELETE removes the value from the attribute.
  • LDAP_MOD_REPLACE replaces all existing values of the attribute.

In addition, if you are specifying binary values in the mod_bvalues field, you should use the bitwise OR operator ( | ) to combine LDAP_MOD_BVALUES with the operation type. For example: 

mod->mod_op = LDAP_MOD_ADD | LDAP_MOD_BVALUES

If you are using the structure to add a new entry, you can specify 0 for the mod_op field (unless you are adding binary values and need to specify LDAP_MOD_BVALUES). See "Adding a New Entry" for details.

mod_type
The attribute type that you want to add, delete, or replace the values of (for example, "sn" or "telephoneNumber").
mod_values
A pointer to a NULL-terminated array of string values for the attribute.
mod_bvalues
A pointer to a NULL-terminated array of berval structures for the attribute.

Note the following:

  • If you specify LDAP_MOD_DELETE in the mod_op field and you remove all values in an attribute, the attribute is removed from the entry.
  • If you specify LDAP_MOD_DELETE in the mod_op field and NULL in the mod_values field, the attribute is removed from the entry.
  • If you specify LDAP_MOD_REPLACE in the mod_op field and NULL in the mod_values field, the attribute is removed from the entry.
  • If you specify LDAP_MOD_REPLACE in the mod_op field and the attribute does not exist in the entry, the attribute is added to the entry.
  • If you specify LDAP_MOD_ADD in the mod_op field and the attribute does not exist in the entry, the attribute is added to the entry.

If you've allocated memory for the structures yourself, you should free the structures when you're finished by calling the ldap_mods_free() function.

The following section of code sets up an LDAPMod structure to change the email address of a user's entry to "bjensen@example.com":

Code Example 17-1 - Setting up an LDAPMod structure

LDAPMod attribute1;
LDAPMod *list_of_attrs[2];
char *mail_values[] = { "bjensen@example.com", NULL };
char *dn;
...
/* Identify the entry that you want changed */
char *dn = "uid=bjensen, ou=People, dc=example,dc=com";

/* Specify that you want to replace the value of an attribute */
attribute1.mod_op = LDAP_MOD_REPLACE;

/* Specify that you want to change the value of the mail attribute */
attribute1.mod_type = "mail";

/* Specify the new value of the mail attribute */
attribute1.mod_values = mail_values;

/* Add the change to the list of attributes that you want changed */
list_of_attrs[0] = &attribute_change;
list_of_attrs[1] = NULL;

/* Update the entry with the change */
if ( ldap_modify_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
  ldap_perror( ld, "ldap_modify_s" );
  return( 1 );
}
...

LDAP_REBINDPROC_CALLBACK

LDAP_REBINDPROC_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and specify it when calling the ldap_set_rebind_proc() function, your function will be called by your LDAP client. The client will call your function to retrieve authentication information when automatically following referrals to other servers.

The prototype specified by this data type is: 

typedef int (LDAP_CALL LDAP_CALLBACK
  LDAP_REBINDPROC_CALLBACK)( LDAP *ld, char **dnp, char **passwdp,
  int *authmethodp, int freeit, void *arg);

For information on the arguments, return values, and purpose of this function, see ldap_set_rebind_proc().

LDAPsortkey

LDAPsortkey represents a server control used to specify that the server should sort the search results before sending them back to the client. Controls are part of the LDAPv3 protocol.

For example, you can use LDAPsortkey to specify that you want the server to sort search results by the roomNumber attribute.

LDAPsortkey is defined as follows: 

typedef struct LDAPsortkey {
  char *sk_attrtype;
  char *sk_matchruleoid;
  int sk_reverseorder;
} LDAPsortkey;

The fields in this structure are described below:

sk_attrtype
Name of the attribute that you want to use for sorting.
sk_matchruleoid
Object identifier (OID) of the matching rule that you want to use for sorting.
sk_reverseorder

Specifies whether or not the results are sorted in reverse order. This field can have one of the following values:

  • A non-zero value specifies that the results should be sorted in reverse order.
  • 0 specifies that the results should be sorted in normal (forward) order.

To create an array of LDAPsortkey structures, you can call the ldap_create_sort_keylist() function.

To free an array of LDAPsortkey structures, you can call the ldap_free_sort_keylist() function.

LDAP_TF_GET_ERRNO_CALLBACK

LDAP_TF_GET_ERRNO_CALLBACK specifies the prototype for a callback function. This function is called by your LDAP client when it needs to get the value of the errno variable for a thread.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_TF_GET_ERRNO_CALLBACK) ( void );

For more details on the errno variable, see ldap_thread_fns.

LDAP_TF_SET_ERRNO_CALLBACK

LDAP_TF_SET_ERRNO_CALLBACK specifies the prototype for a callback function. This function is called by your LDAP client when it needs to set the value of the errno variable for a thread.

The prototype specified by this data type is: 

typedef void (LDAP_C LDAP_CALLBACK
  LDAP_TF_SET_ERRNO_CALLBACK)( int );

For more details on the errno variable, see ldap_thread_fns.

LDAP_TF_GET_LDERRNO_CALLBACK

LDAP_TF_GET_LDERRNO_CALLBACK specifies the prototype for a callback function. This function is called by your LDAP client when it needs to retrieve the LDAP result code for an operation.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_TF_GET_LDERRNO_CALLBACK)( char **, char **, void * );

If you define a function with this prototype and set it in the ldap_thread_fns structure, your callback function is called when the ldap_get_lderrno() function is called. The arguments of ldap_get_lderrno() are passed to your function, and the value returned by your function is returned by ldap_get_lderrno().

For more details on the arguments and return values that your function must use, see ldap_get_lderrno().

LDAP_TF_SET_LDERRNO_CALLBACK

LDAP_TF_SET_LDERRNO_CALLBACK specifies the prototype for a callback function. This function is called by your LDAP client when it needs to set the LDAP result code for an operation.

The prototype specified by this data type is: 

typedef void (LDAP_C LDAP_CALLBACK
  LDAP_TF_SET_LDERRNO_CALLBACK)( int, char *, char *, void * );

If you define a function with this prototype and set it in the ldap_thread_fns structure, your callback function is called when the ldap_set_lderrno() function is called. The arguments of ldap_set_lderrno() are passed to your function.

For more details on the arguments that your function must use, see ldap_set_lderrno().

LDAP_TF_MUTEX_ALLOC_CALLBACK

LDAP_TF_MUTEX_ALLOC_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_thread_fns structure, your function will be called by your LDAP client when it needs to allocate a mutex.

The prototype specified by this data type is: 

typedef void *(LDAP_C LDAP_CALLBACK
  LDAP_TF_MUTEX_ALLOC_CALLBACK)( void );

LDAP_TF_MUTEX_FREE_CALLBACK

LDAP_TF_MUTEX_FREE_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_thread_fns structure, your function will be called by your LDAP client when it needs to free a mutex.

The prototype specified by this data type is: 

typedef void (LDAP_C LDAP_CALLBACK
  LDAP_TF_MUTEX_FREE_CALLBACK)( void * );

LDAP_TF_MUTEX_LOCK_CALLBACK

LDAP_TF_MUTEX_LOCK_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_thread_fns structure, your function will be called by your LDAP client when it needs to lock a mutex.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_TF_MUTEX_LOCK_CALLBACK)( void * );

LDAP_TF_MUTEX_TRYLOCK_CALLBACK

This function prototype is not supported in this release of the LDAP C SDK.

LDAP_TF_MUTEX_UNLOCK_CALLBACK

LDAP_TF_MUTEX_UNLOCK_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_thread_fns structure, your function will be called by your LDAP client when it needs to unlock a mutex.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_TF_MUTEX_UNLOCK_CALLBACK)( void * );

LDAP_TF_SEMA_ALLOC_CALLBACK

This function prototype is not supported in this release of the LDAP C SDK.

LDAP_TF_SEMA_FREE_CALLBACK

This function prototype is not supported in this release of the LDAP C SDK.

LDAP_TF_SEMA_POST_CALLBACK

This function prototype is not supported in this release of the LDAP C SDK.

LDAP_TF_SEMA_WAIT_CALLBACK

This function prototype is not supported in this release of the LDAP C SDK.

LDAP_TF_THREADID_CALLBACK

LDAP_TF_THREADID_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and set it in the ldap_thread_fns structure, your function will be called when the LDAP C SDK needs to identify a thread. This callback function should return an identifier that is unique to the calling thread, much like the POSIX pthread_self() function does.

The prototype specified by this data type is: 

typedef void *(LDAP_C LDAP_CALLBACK
  LDAP_TF_THREADID_CALLBACK)( void );

ldap_thread_fns

The ldap_thread_fns structure contains a set of pointers to functions that you want to use when write a multithreaded client.

The ldap_thread_fns structure is defined as follows: 

struct ldap_thread_fns {
  LDAP_TF_MUTEX_ALLOC_CALLBACK *ltf_mutex_alloc;
  LDAP_TF_MUTEX_FREE_CALLBACK *ltf_mutex_free;
  LDAP_TF_MUTEX_LOCK_CALLBACK *ltf_mutex_lock;
  LDAP_TF_MUTEX_UNLOCK_CALLBACK *ltf_mutex_unlock;
  LDAP_TF_GET_ERRNO_CALLBACK *ltf_get_errno;
  LDAP_TF_SET_ERRNO_CALLBACK *ltf_set_errno;
  LDAP_TF_GET_LDERRNO_CALLBACK *ltf_get_lderrno;
  LDAP_TF_SET_LDERRNO_CALLBACK *ltf_set_lderrno;
  void *ltf_lderrno_arg;
};

The fields in this structure are described below:

ltf_mutex_alloc
Function pointer for allocating a mutex. This function is called by the client when needed if the function pointer is not NULL. The function must have the prototype specified by LDAP_TF_MUTEX_ALLOC_CALLBACK.
ltf_mutex_free
Function pointer for freeing a mutex. This function is called by the client when needed if the function pointer is not NULL. The function must have the prototype specified by LDAP_TF_MUTEX_FREE_CALLBACK.
ltf_mutex_lock
Function pointer for locking critical sections of code. This function is called by the client when needed if the function pointer is not NULL. The function must have the prototype specified by LDAP_TF_MUTEX_LOCK_CALLBACK.
ltf_mutex_unlock
Function pointer for unlocking critical sections of code. This function is called by the client when needed if the function pointer is not NULL. The function must have the prototype specified by LDAP_TF_MUTEX_UNLOCK_CALLBACK.
ltf_get_errno

Function pointer for getting the value of the errno variable. This function is called by the client when needed if the function pointer is not NULL.

In a threaded environment, errno is typically redefined so that it has a value for each thread, rather than a global value for the entire process. This redefinition is done at compile time. Because the libldap library does not know what method your code and threading environment will use to get the value of errno for each thread, it calls this function to obtain the value of errno.

The function must have the prototype specified by LDAP_TF_GET_ERRNO_CALLBACK.

ltf_set_errno

Function pointer for setting the value of the errno variable. This function is called by the client when needed if the function pointer is not NULL.

In a threaded environment, errno is typically redefined so that it has a value for each thread, rather than a global value for the entire process. This redefinition is done at compile time. Because the libldap library does not know what method your code and threading environment will use to get the value of errno for each thread, it calls this function to set the value of errno.

The function must have the prototype specified by LDAP_TF_SET_ERRNO_CALLBACK.

ltf_get_lderrno

Function pointer for getting error values from calls to functions in the libldap library. This function is called by the client as needed if the function pointer isn't NULL.

If this function pointer is not set, the libldap library records these errors in fields in the LDAP structure.

The function must have the prototype specified by LDAP_TF_GET_LDERRNO_CALLBACK.

ltf_set_lderrno

Function pointer for setting error values from calls to functions in the libldap library. This function is called by the client as needed if the function pointer isn't NULL.

If this function pointer is not set, the libldap library records these errors in fields in the LDAP structure.

The function must have the prototype specified by LDAP_TF_SET_LDERRNO_CALLBACK.

ltf_lderrno_arg
Additional parameter passed to the functions for getting and setting error values from calls to functions in the libldap library. (*ltf_get_lderrno) and (*ltf_set_lderrno) identify these functions.

For an example of setting up the ldap_thread_fns structure, see Chapter 16 - Writing Multithreaded Clients.

LDAPURLDesc

LDAPURLDesc is a type of structure that represents the components of an LDAP URL. LDAP URLs have the following syntax: 

ldap://hostport/dn[?attributes[?scope[?filter]]]

For example: 

ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich

Calling the ldap_url_parse() routine creates an LDAPURLDesc structure containing the components of the URL. To free the LDAPURLDesc structure, call the ldap_free_urldesc() routine.

LDAPURLDesc is defined as follows: 

typedef struct ldap_url_desc {
  char *lud_host;
  int lud_port;
  char *lud_dn;
  char **lud_attrs;
  int lud_scope;
  char *lud_filter;
  unsigned long lud_options;
} LDAPURLDesc;

The fields in this structure are described below:

lud_host
Name of the host in the URL.
lud_port
Number of the port in the URL.
lud_dn
Distinguished name in the URL. This "base entry" DN identifies the starting point of the search.
lud_attrs
Pointer to a NULL-terminated list of the attributes specified in the URL.
lud_scope

Integer representing the scope of the search specified in the URL:

  • LDAP_SCOPE_BASE specifies a search of the base entry.
  • LDAP_SCOPE_ONELEVEL specifies a search of all entries one level under the base entry (not including the base entry).
  • LDAP_SCOPE_SUBTREE specified a search of all entries at all levels under the base entry (including the base entry).
lud_filter
Search filter included in the URL.
lud_options
Options (if LDAP_URL_OPT_SECURE, indicates that the protocol is ldaps:// instead of ldap://).

For example, suppose you pass the following URL to the ldap_url_parse() function: 

ldap://ldap.example.com:5000/dc=example,dc=com?cn,mail, \
  telephoneNumber?sub?(sn=Jensen)

The resulting LDAPURLDesc structure (ludpp, in this example) will contain the following values:

ludpp->lud_host
ldap.example.com
ludpp->lud_port
5000
ludpp->lud_dn
dc=example,dc=com
ludpp->lud_attrs[0]
cn
ludpp->lud_attrs[1]
mail
ludpp->lud_attrs[2]
telephoneNumber
ludpp->lud_attrs[3]
NULL
ludpp->lud_scope
LDAP_SCOPE_SUBTREE
ludpp->lud_filter
(sn=Jensen)

LDAP_VALCMP_CALLBACK

LDAP_VALCMP_CALLBACK specifies the prototype for a callback function. If you define a function with this prototype and specify it when calling the ldap_sort_values() function, your function will be called by your LDAP client. The client will call your function to sort a specified set of values.

The prototype specified by this data type is: 

typedef int (LDAP_C LDAP_CALLBACK
  LDAP_VALCMP_CALLBACK)(const char**, const char**);

For information on the arguments, return values, and purpose of this function, see ldap_sort_values().

LDAPVersion

LDAPVersion is deprecated; you should use the function ldap_get_option() in its place (it is documented here for backward compatibility only).

LDAPVersion contains version information about the LDAP C SDK. Call the ldap_version() function to return a pointer to an LDAPVersion structure containing the version information.

LDAPVersion is defined as follows: 

typedef struct _LDAPVersion {
  int sdk_version;
  int protocol_version;
  int SSL_version;
  int security_level;
} LDAPVersion;

The fields in this structure are described below:

sdk_version
Version number of the LDAP C SDK multiplied by 100 (for example, the value 100 in this field represents version 1.0).
protocol_version
Highest supported LDAP protocol version multiplied by 100 (for example, the value 300 in this field represents LDAPv3).
SSL_version
Supported SSL version multiplied by 100 (for example, the value 300 in this field represents SSL 3.0).
security_level
Level of encryption supported in bits (for example, 128 for domestic or 40 for export). If SSL is not enabled, the value of this field is LDAP_SECURITY_NONE.

LDAPVirtualList

LDAPVirtualList specifies the information that can be used to create a "virtual list view" control. This LDAPv3 control is designed to allow the client to retrieve subsets of search results to display in a "virtual list box".

This control is OID 2.16.840.1.113730.3.4.9, or LDAP_CONTROL_VLVREQUEST as defined in ldap.h.

This control is supported by the Netscape Directory Server, version 4.0 and later. For information on determining if a server supports this or other LDAPv3 controls, see "Determining If the Server Supports LDAPv3".

A virtual list box is typically a graphical user interface that displays a long list of entries with a few entries visible. End users can display different sections of the list by scrolling up or down.

To display the list of entries, the client usually does not retrieve the entire list of entries from the server. Instead, the client just retrieves the subset of entries to be displayed to the end user.

The virtual list view control provides the means for your client to request and retrieve certain subsets of a long, sorted list of entries. The control specifies the following information:

  • The entry in the list that is currently selected.
  • The number of entries to be displayed in the list before the selected item.
  • The number of entries to be displayed in the list after the selected entry.

The currently selected entry can be identified in one of the following ways:

  • By the index of the entry in the entire list (in which case, the control specifies both the offset of the entry and the total number of entries in the list).
  • By the value of the entry (in which case, the control specifies that value).

For example, a virtual list view control might specify that you want to retrieve entries 15 through 24 in a list of 100 results with entry 20 being the selected entry. The control uses the following information to specify this:

  • The selected entry is the 20th entry from the top (in other words, the index or offset of the entry is 20) of a list of 100.
  • Get 5 entries before the selected entry in the list (entries 15 - 19).
  • Get 4 entries after the selected entry in the list (entries 21 - 24).

As another example, a virtual list view control might specify that you want to retrieve a subset of entries that start with the letter "c" or a later letter in the alphabet. The control might specify the following information:

  • The selected entry is the first entry that starts with the letter "c". (The size of the list is not relevant in determining the selected entry in this case.)
  • Get 5 entries before the selected entry in the list.
  • Get 4 entries after the selected entry in the list.

LDAPVirtualList is defined as follows: 

typedef struct ldapvirtuallist {
  unsigned long ldvlist_before_count;
  unsigned long ldvlist_after_count;
  char *ldvlist_attrvalue;
  unsigned long ldvlist_index;
  unsigned long ldvlist_size;
  void *ldvlist_extradata;
} LDAPVirtualList;

The fields in this structure are described below:

ldvlist_before_count
Number of entries before the selected entry that you want to retrieve.
ldvlist_after_count
Number of entries after the selected entry that you want to retrieve.
ldvlist_attrvalue

Specifies the value that you want to find in the list. The selected entry in the list is the first entry that is greater than or equal to this value.

If this field is NULL, the ldvlist_index and ldvlist_size fields are used to determine the selected entry instead.

ldvlist_index
If the ldvlist_attrvalue field is NULL, specifies the offset or index of the selected entry in the list. This field is used in conjunction with the ldvlist_size field to identify the selected entry.
ldvlist_size
If the ldvlist_attrvalue field is NULL, specifies the total number items in the list. This field is used in conjunction with the ldvlist_index field to identify the selected entry.
ldvlist_extradata
Reserved for application-specific use. Note that this data is not used in the virtual list view control.

After you create an LDAPVirtualList structure and specify values for its fields, you can create the virtual list view control by calling the function ldap_create_virtuallist_control().

You can pass this control and a server-side sorting control (created by calling the ldap_create_sort_keylist() function and the ldap_create_sort_control() function) to the ldap_search_ext() or ldap_search_ext_s() function.

To get the virtual list view response control sent back from the server, call the ldap_parse_result() function to get the list of controls returned by the server, then call the ldap_parse_virtuallist_control() function to retrieve information from the control.

For more information about this control, see "Using the Virtual List View Control."