Previous Contents Index DocHome Next |
Netscape LDAP SDK for C LDAP SDK for C |
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 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.
struct berval {
unsigned long bv_len;
char *bv_val;
};The fields in this structure are described below:
Table 17-1    berval field descriptions
bv_len
bv_val
Use a berval structure when working with attributes that contain binary data (such as a JPEG or audio file).
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 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 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:
To create an LDAP structure, call the ldap_init() or ldapssl_init() function.
To view or modify the properties of the connection, call the ldap_get_option() and ldap_set_option() functions.
To close the connection and free the LDAP structure, call the ldap_unbind() or ldap_unbind_s() function.
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 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.)
LDAPControl is defined as follows:
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.
- 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.
- Note that the Netscape LDAP SDK for C, v4.1 does not currently support any client controls.
typedef struct ldapcontrol {
char *ldctl_oid;
struct berval ldctl_value;
char ldctl_iscritical;
} LDAPControl;The fields in this structure are described below:
Table 17-2    LDAPControl field descriptions
ldctl_oid
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:
For more information on LDAP controls, see Chapter 14 "Working with LDAP Controls."
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 SDK for C 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 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 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 SDK for C 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:
Table 17-3    ldap_dns_fns field descriptions
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.
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 SDK for C 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:
Table 17-4    ldap_extra_thread_fns field descriptions
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 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 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:
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"
Filter: (mail=@)
Description: email address is
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:
Table 17-6    LDAPHostEnt field descriptions
ldaphe_name
ldaphe_aliases
ldaphe_addrtype
ldaphe_length
ldaphe_addr_list
List of addresses for this host (as returned by the name server).
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 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 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 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 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 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 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 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 );
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:
Table 17-7    ldap_io_fns field descriptions
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 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.
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.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.
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.
Use the following functions to work with the cache: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.
To create an LDAPMemCache structure, call the ldap_memcache_init() function.
To associate an LDAPMemCache structure with a connection handle (an LDAP structure), call the ldap_memcache_set() function.
To get the LDAPMemCache structure that is associated with a connection handle (an LDAP structure), call the ldap_memcache_get() function.
To get the cache to proactively remove expired items, call the ldap_memcache_update() function.
To remove entries from the cache, call the ldap_memcache_flush() function.
To free the LDAPMemCache structure, call ldap_memcache_destroy().
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 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:
Table 17-8    LDAPMod field descriptions
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
Note: 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.
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've allocated memory for the structures yourself, you should free the structures when you're finished by calling the ldap_mods_free() function.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.
The following section of code sets up an LDAPMod structure to change the email address of a user's entry to "bjensen@airius.com":
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 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:
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 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 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 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 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 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 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 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 SDK for C.
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 * );
This function prototype is not supported in this release of the LDAP SDK for C.
This function prototype is not supported in this release of the LDAP SDK for C.
This function prototype is not supported in this release of the LDAP SDK for C.
This function prototype is not supported in this release of the LDAP SDK for C.
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 SDK for C 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 );
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:
Table 17-10    ldap_thread_fns field descriptions
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 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]]]
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:
For example, suppose you pass the following URL to the ldap_url_parse() function:
ldap://ldap.iplanet.com:5000/dc=airius,dc=com?cn,mail, \
telephoneNumber?sub?(sn=Jensen)The resulting LDAPURLDesc structure (ludpp, in this example) will contain the following values:
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 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 SDK for C. 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:
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; and all iPlanet Directory Server versions. 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 currently selected entry can be identified in one of the following ways: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.
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).
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:By the value of the entry (in which case, the control specifies that value).
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.
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: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).
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.)
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:
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."
Previous Contents Index DocHome Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated November 16, 2000