| Sun Java System LDAP SDK for C Programming Guide |
Chapter 16
Data Type ReferenceThis chapter contains reference material for the public data types and structures of the Sun™ Java System LDAP SDK for C. The first sections detail the data types of the grouped into task categories. The last section is an alphabetical listing of the same information. The chapter contains the following sections:
ConventionsThe following sections detail certain conventions and concepts used in the LDAP SDK for C.
Typrographical
Table 16-1 lists the typographical conventions used in the names of data types and structures.
Deprecated Structures
A deprecated API is one that we recommend you no longer use. While deprecated APIs are currently still implemented, they may be removed in future versions of the LDAP SDK for C. Applications should not rely on a deprecated structure as it can and will disappear without notice.
Structure Summary by TaskIn the following sections, the structures defined by the LDAP SDK for C are grouped into task categories.
BER Structures
The structures listed in Table 16-2 represent data encoded using the Basic Encoding Rules (BER). The lber.h header file contains many other type definitions; the ones listed here are those likely to be handled directly. All others are used internally by the various functions of the LDAP SDK for C.
Table 16-2 BER Structures
Structure
Description
berval represents binary data encoded using BER.
BerElement indicates the current position during a traversal of an attribute list.
Structures for the Core API
The structures listed in Table 16-3 are used by the core functions of the LDAP SDK for C. These structures are used directly as argument or return types by functions that provide the core functionality.
Table 16-3 Core API Structures
Structure
Description
LDAP represents a connection handle to the LDAP server.
LDAPMessage represents 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.
LDAPMod specifies changes to an attribute in an directory entry.
LDAPControl represents a client or server control associated with an LDAP operation.
LDAPAPIInfo represents information about the version of the LDAP SDK for C being implemented
LDAPAPIFeatureInfo represents information about the extended features.
Structures for API Extensions
The structures listed in Table 16-4 are needed for extensions to the standard API within the LDAP SDK for C. These structures are used directly as arguments or return types by the functions that provide the extended functionality.
Table 16-4 API Extension Structures
Structure
Description
LDAPsortkey represents a server control used to specify that the server should sort the search results before sending them back to the client.
LDAPVirtualList specifies the information that can be used to create a virtual list view control.
LDAPURLDesc represents the components of an LDAP URL.
LDAPFiltInfo represents information about a filter in a filter configuration file.
LDAPFiltDesc is a type of structure returned when you call ldap_init_getfilter() to load a filter configuration file.
FriendlyMap represents the mapping between a list of standard attribute names and their user friendly counterparts.
LDAPMemCache represents an in-memory, client-side cache.
Note
Many other types, especially prototypes for callback functions, are associated with controls. These are listed separately in the subsequent sections of this chapter. The concept of controls themselves are defined and discussed in Chapter 13, "Working with LDAP Controls."
Referral Binding Callback
This prototype for a callback function will retrieve authentication information when automatically following referrals to other servers.
Table 16-5 Referral Binding Data Type
Data Type
Description
Retrieves authentication information when following referrals to other servers.
Client-Side Sorting Callbacks
The prototype structures listed in Table 16-6 are extensions to the LDAP SDK for C that implement client side sorting of entries.
Extended I/O Control
Table 16-7 lists the prototypes and structures used in the extended I/O control, an extension to the standard API.
Memory Management Control
The prototypes and structures listed in Table 16-8 are used in memory management control, an extension to the standard API. They allow developers to specify their own memory allocation mechanisms and functions.
Table 16-8 Memory Management Datatypes
Data Type
Description
This structure holds the memory allocation callback functions.
LDAP_MALLOC_CALLBACK
LDAP_CALLOC_CALLBACK
LDAP_REALLOC_CALLBACK
LDAP_FREE_CALLBACKThese callbacks allow developers to specify their own memory allocation mechanisms.
Thread Signaling Controls
The prototypes and structures listed in Table 16-9 are used in the thread signaling control, an extension to the standard API.
Deprecated and Outdated Types
Deprecated types are those being dropped from the standard or from the extensions to the LDAP SDK for C. They are not guaranteed to be defined in future versions of the API. However, all of these types are still defined in this version for backwards compatibility. Table 16-10 lists the deprecated prototypes.
Table 16-10 Deprecated Data Types and Their Replacements
Data Type
Replacement
Provides a way to be cancel a process, for example, by a user or because some other condition occurs.
ldap_cache_fns
LDAP_CF_BIND_CALLBACK
LDAP_CF_UNBIND_CALLBACK
LDAP_CF_SEARCH_CALLBACK
LDAP_CF_COMPARE_CALLBACK
LDAP_CF_ADD_CALLBACK
LDAP_CF_DELETE_CALLBACK
LDAP_CF_MODIFY_CALLBACK
LDAP_CF_MODRDN_CALLBACK
LDAP_CF_RESULT_CALLBACK
LDAP_CF_FLUSH_CALLBACKldap_cache_fns is a deprecated structure and the typedef declarations associated with it have also been deprecated.
Replaced by the LDAPAPIInfo type which is returned by the ldap_get_option() function using the LDAP_OPT_API_INFO option.
While not officially deprecated, other data types are outdated because they have superceded by new types. Outdated types may become deprecated in future releases of the LDAP SDK for C. Table 16-11 lists the outdated types and the newer types which implement the same functionality.
Table 16-11 Outdated Types and Their New Equivalent
Old Data Type
New, Equivalent Data Type
LDAPHostEnt
LDAP_DNSFN_GETHOSTBYNAME
LDAP_DNSFN_GETHOSTBYADDR
ldap_dns_fnsThe DNS resolver callbacks are an outdated extension to the API. The new way of specifying host information is through the LDAP_X_EXTIOF_CONNECT_CALLBACK prototype.
LDAP_IOF_CLOSE_CALLBACK
LDAP_IOF_CONNECT_CALLBACK
LDAP_IOF_IOCTL_CALLBACK
LDAP_IOF_READ_CALLBACK
LDAP_IOF_SELECT_CALLBACK
LDAP_IOF_SOCKET_CALLBACK
LDAP_IOF_SSL_ENABLE_CALLBACK
LDAP_IOF_WRITE_CALLBACK
ldap_io_fnsReplaced by the types for extended I/O functionality detailed in Table 16-7.
Structures AlphabeticallyThe following sections detail the structures and controls of the LDAP SDK for C in alphabetical order.
bervalberval is a structure that represents binary data encoded using simplified Basic Encoding Rules (BER).
Description
Use a berval structure when working with attributes that contain binary data (such as a graphic or audio file). The data and the size of the data are both included in a berval structure. Code Example 16-1 illustrates the definition of the berval structure.
The fields in the berval structure are described in Table 16-12.
Table 16-12 berval Field Descriptions
Field
What It Contains
bv_len
The length of the data in bytes.
bv_val
A pointer to the binary data itself.
BerElementThe BerElement structure represents data encoded using the Basic Encoding Rules (BER).
Description
You use this opaque data type to keep track of the current attribute during the traversal of an attribute list. Calling the ldap_first_attribute() function allocates memory for a BerElement structure and initializes it to select the values of the first sttribute in the entry. Subsequently, ldap_next_attribute() is called to obtain the name of each remaining attribute and set BerElement to select their values. Once BerElement has been set to select an attribute's values, ldap_get_values() can be used to obtain all of them from the buffer. When you are done reading the attributes, you need to free the BerElement structure from memory by calling the ldap_ber_free() function. (A BerElement structure can also be allocated by calling the ber_alloc_t() or the ber_init() function. In these cases, free the memory allocated to the BerElement structure by using the ber_free() function.)
Note
The BerElement definition is not completely exposed in lber.h because the fields within the structure are not intended to be accessible to clients.
FriendlyMapFriendlyMap represents the mapping between a list of standard attribute names and their user-friendly counterparts. For example, you can represent the list of two-letter state codes (CA, IA) with their corresponding state names (California, Iowa), or map Country ISO codes to the full country names, in a FriendlyMap structure.
Note
FriendlyMap is not completely defined in ldap-extension.h because the fields within the structure are not intended to be accessible to clients.
Related Functions
- ldap_friendly_name() allocates a FriendlyMap structure and reads a list of of standard attribute names and their user friendly counterparts from a file.
- ldap_free_friendlymap() frees the memory allocated for a FriendlyMap structure.
LDAPLDAP is an opaque data type representing a connection with the LDAP server. It is initialized through a call to either the ldap_init() or ldapssl_init() function. LDAP maintains the state of an LDAP session for the duration of the connection. When you call functions that perform LDAP operations on an LDAP server (for example, ldap_search_ext() to search the directory or ldap_modify_ext() to update an entry), you need to pass a pointer to this connection handle. With the LDAP structure, you can also:
- Call the ldap_get_option() and ldap_set_option() functions to view or modify the properties of the connection.
- Call the ldap_unbind() or ldap_unbind_s() function to close the connection and free the LDAP structure.
LDAPAPIFeatureInfoLDAPAPIFeatureInfo is a structure that represents information about the extended features of the LDAP SDK for C. Code Example 16-2 illustrates the definition of the LDAPAPIFeatureInfo structure.
The LDAPAPIFeatureInfo structure can be retrieved by using a sequence like the one displayed in Code Example 16-3.
Code Example 16-3 Sequence to Retrieve LDAPAPIFeatureInfo
LDAPAPIFeatureInfo ldfi;
ldfi.ldapaif_info_version = LDAP_FEATURE_INFO_VERSION;
ldfi.ldapaif_name = "VIRTUAL_LIST_VIEW";
if ( ldap_get_option( NULL, LDAP_OPT_API_FEATURE_INFO, &ldfi ) == 0 ) ...
Parameters
This structure has the parameters listed in Table 16-13.
Table 16-13 LDAPAPIFeatureInfo Structure Parameters
Parameter
Description
ldapaif_info_version
Specifies the version number of the LDAPAPIFeatureInfo structure. This must be set to LDAP_FEATURE_INFO_VERSION before call to ldap_get_option() is performed.
ldapaif_name
Pointer to NULL-terminated string that specifies the name of the supported feature.
ldapaif_version
Specifies the version number of the supported feature.
LDAPAPIInfoLDAPAPIInfo is a structure that represents information about the API and supported extensions. Code Example 16-4 illustrates the definition of the LDAPAPIInfo structure.
Code Example 16-4 LDAPAPIInfo Definition
#define LDAP_API_INFO_VERSION
typedef struct ldapapiinfo {
int ldapai_info_version; /* version of LDAPAPIInfo (1) */
int ldapai_api_version; /* revision of API supported */
int ldapai_protocol_version; /* highest LDAP version supported */
char **ldapai_extensions; /* names of API extensions */
char *ldapi_vendor_name; /* name of supplier */
int ldapai_vendor_version; /* supplier-specific version times 100 */
} LDAPAPIInfo;
The LDAPAPIInfo structure can be retrieved by using a sequence like the one displayed in Code Example 16-5.
Code Example 16-5 Sequence to Retrieve LDAPAPIInfo
LDAPAPIInfo ldai;
ldai.ldapai_info_version = LDAP_API_INFO_VERSION;
if ( ldap_get_option( NULL, LDAP_OPT_API_INFO, &ldia ) == 0 ) ...
Parameters
This structure has the parameters listed in Table 16-14.
Table 16-14 LDAPAPIInfo Structure Parameters
Parameter
Description
ldapai_info_version
Specifies the version number of the LDAPAPIInfo structure. This must be set to LDAP_API_INFO_VERSION before a call to ldap_get_option() is performed.
ldapai_api_version
Specifies the version number of the API that is supported.
ldapai_protocol_version
Specifies the latest LDAP version supported by the LDAP library.
ldapai_extensions
Points to a NULL-terminated array of character strings that names the supported LDAP extensions. If none are supported, this field is set to NULL. The application is responsible for freeing this memory by calling the ldap_value_free() function.
ldapai_vendor_name
Pointer to a NULL-terminated string that contains the vendor's name. Call the ldap_memfree() function to free the memory.
ldapai_vendor_version
Specifies the vendor’s version of the LDAP libraries.
ldap_cache_fnsldap_cache_fns is a deprecated structure. The following are also deprecated:
See Also
Please see the ldap_memcache_* functions in Chapter 17, "Function Reference" for current usage.
LDAP_CALLOC_CALLBACKThis callback function prototype of ldap_memalloc_fns represents memory allocation.
See Also
LDAP_CANCELPROC_CALLBACKThis callback function prototype is to-be-deprecated.
See Also
ldap_ufn_search_c(), ldap_ufn_search_ct()
LDAP_CF_ADD_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_BIND_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_COMPARE_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_DELETE_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_FLUSH_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_MODIFY_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_MODRDN_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_RESULT_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_SEARCH_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CF_UNBIND_CALLBACKThis callback function prototype of ldap_cache_fns is deprecated.
LDAP_CMP_CALLBACKLDAP_CMP_CALLBACK specifies the prototype for a comparison callback function used when sorting values. If you define a function with this prototype and specify it when calling ldap_sort_entries() or ldap_multisort_entries(), it will be called by your LDAP client to sort a specified set of entries. Code Example 16-6 is the prototype.
Code Example 16-6 LDAP_CMP_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_CMP_CALLBACK)(const char*, const char*);
See Also
ldap_sort_entries(), ldap_multisort_entries().
LDAPControlLDAPControl represents a client or server control associated with an LDAP operation. If set as a server control, it is sent to the server along with operation requests; if set as a client control, it is interpreted locally by the client.
Note
Controls are part of the LDAPv3. You can use a control to extend the functionality of an LDAP operation. There are two basic types of controls described in the LDAPv3:
- 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 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.
Sun Java System LDAP SDK for C does not currently support any client controls. For more information on LDAP controls, see Chapter 13, "Working with LDAP Controls."
Code Example 16-7 illustrates how LDAPControl is defined.
Code Example 16-7 Definition of LDAPControl
typedef struct ldapcontrol {
char *ldctl_oid;
struct berval ldctl_value;
char ldctl_iscritical;
} LDAPControl;
Table 16-15 describes the fields in this structure.
Table 16-15 LDAPControl Field Descriptions
Field
What It Contains
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:
LDAP_DNSFN_GETHOSTBYADDRLDAP_DNSFN_GETHOSTBYADDR specifies the prototype for a callback function equivalent to the gethostbyaddr_r() function available on some UNIX® platforms.
Caution
While not officially deprecated, the functionality of this callback prototype is superceded by the extended I/O functions. The new way of specifying host information is through the LDAP_X_EXTIOF_CONNECT_CALLBACK prototype.
Description
If you define a function with this prototype and set it in the ldap_dns_fns structure, your function will be called by the SDK on behalf of your LDAP client if it needs to get the host name of the LDAP server to which it is connected.
Note
In this version of the LDAP SDK for C, the functions of the API never call this function, and your implementation will never be executed. Therefore, its implementation is optional.
Code Example 16-8 is the prototype specified by this data type.
Code Example 16-8 LDAP_DNSFN_GETHOSTBYADDR Prototype
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_GETHOSTBYNAMELDAP_DNSFN_GETHOSTBYNAME specifies the prototype for a callback function equivalent to the gethostbyname_r() function available on some UNIX platforms.
Caution
While not officially deprecated, the functionality of this callback prototype is superceded by the extended I/O functions. The new way of specifying host information is through the LDAP_X_EXTIOF_CONNECT_CALLBACK prototype.
Description
If you define a function with this prototype and set it in the ldap_dns_fns structure, your function will be called by the SDK on behalf of your LDAP client to get the host entry for the LDAP server when connecting to the server. Code Example 16-9 is the prototype specified by this data type.
Code Example 16-9 LDAP_DNSFN_GETHOSTBYNAME Prototype
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_fnsldap_dns_fns contains a set of pointers to DNS functions (equivalent to the gethostbyname_r() and gethostbyaddr_r() functions available on some UNIX platforms).
Caution
While not officially deprecated, the functionality of this structure is superceded by the extended I/O functions. The new way of specifying host information is through the LDAP_X_EXTIOF_CONNECT_CALLBACK prototype.
Description
You can use this structure if you want the SDK to call these functions when looking up the host name 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. The function must have the prototype specified by LDAP_DNSFN_GETHOSTBYADDR. If NULL, the standard built-in OS routine is used.
After you set the fields in this structure, you can register the functions for use by calling the ldap_set_option() function and setting the LDAP_OPT_DNS_FN_PTRS option to this structure. Code Example 16-10 illustrates how ldap_dns_fns is defined.
Code Example 16-10 ldap_dns_fns Definition
struct ldap_dns_fns {
void *lddnsfn_extradata;
int lddnsfn_bufsize;
LDAP_DNSFN_GETHOSTBYNAME *lddnsfn_gethostbyname;
LDAP_DNSFN_GETHOSTBYADDR *lddnsfn_gethostbyaddr;
};
Table 16-16 describes the fields in this structure.
Table 16-16 ldap_dns_fns Field Descriptions
Field
What It Contains
lddnsfn_extradata
Value passed in the extradata argument of the LDAP_DNSFN_GETHOSTBYADDR and LDAP_DNSFN_GETHOSTBYNAME 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_GETHOSTBYNAME 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.
ldap_extra_thread_fnsThe ldap_extra_thread_fns structure contains a set of pointers to additional functions that you can use when writing a multithreaded client. Your client calls these functions when getting results from the LDAP structure.
Tip
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 for use by calling the ldap_set_option() function and setting the LDAP_OPT_EXTRA_THREAD_FN_PTRS option to this structure. Code Example 16-11 illustrates the definition of the ldap_extra_thread_fns structure.
Code Example 16-11 ldap_extra_thread_fns Definition
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;
};
Table 16-17 describes the fields in this structure.
Table 16-17 ldap_extra_thread_fns Field Descriptions
Field
What It Contains
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 finction is called by the client if needed when 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 14, "Writing Multithreaded Clients."
LDAPFiltDescLDAPFiltDesc is a structure that is returned when you call ldap_init_getfilter() to load a filter configuration file.
Note
The LDAPFiltDesc definition is not completely exposed in ldap-extension.h because the fields within the structure are not intended to be accessible to clients.
Description
After calling the ldap_init_getfilter() function, use the pointer to the returned LDAPFiltDesc structure in subsequent calls to get information about filters in the filter configuration file.
LDAPFiltInfoLDAPFiltInfo represents information about a filter in the filter configuration file.
Description
When you call the ldap_getfirstfilter() or ldap_getnextfilter() functions to get a filter from the filter configuration file, they return a pointer to an LDAPFiltInfo structure containing the information about the filter. Code Example 16-12 illustrates how LDAPFiltInfo is defined.
Code Example 16-12 LDAPFiltInfo Definition
typedef struct ldap_filt_info {
char *lfi_filter;
char *lfi_desc;
int lfi_scope;
int lfi_isexact;
struct ldap_filt_info *lfi_next;
} LDAPFiltInfo;
Table 16-18 details the fields in LDAPFiltInfo.
Table 16-18 LDAPFilterInfo Field Descriptions
Field
What It Contains
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 DN.
- LDAP_SCOPE_ONELEVEL specifies that the search will be restricted to the entries at the level beneath the current DN.
- LDAP_SCOPE_SUBTREE specifies that the search will encompass entries at all levels beneath the current DN.
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):
lfi_next
Pointer to the LDAPFiltInfo structure representing the next filter in the filter list.
Code Example 16-13 prints out information about a filter.
Code Example 16-13 Sample LDAPFiltInfo Code
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
LDAP_FREE_CALLBACKThis callback function prototype of ldap_memalloc_fns is used to free allocated memory.
See Also
LDAPHostEntThe LDAPHostEnt structure represents an entry for a host found by a domain name server.
Caution
While not officially deprecated, the functionality of this callback prototype is superceded by the extended I/O functions. The new way of specifying host information is through the LDAP_X_EXTIOF_CONNECT_CALLBACK prototype.
Description
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, they should return the host entry in this type of structure.
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. Code Example 16-14 illustrates how LDAPHostEnt is defined.
Code Example 16-14 LDAPHostEnt Definition
typedef struct LDAPHostEnt {
char *ldaphe_name;
char **ldaphe_aliases;
int ldaphe_addrtype;
int ldaphe_length;
char **ldaphe_addr_list;
} LDAPHostEnt;
Table 16-19 defines the fields in the LDAPHostEnt structure.
Table 16-19 LDAPHostEnt Field Descriptions
Field
What It Contains
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)
See Also
LDAP_DNSFN_GETHOSTBYADDR, LDAP_DNSFN_GETHOSTBYNAME
LDAP_IOF_CLOSE_CALLBACKLDAP_IOF_CLOSE_CONNECT_CALLBACK specifies the prototype for a callback function equivalent to the standard close() system call.
Description
If you define a function with this prototype and set it in the ldap_io_fns structure, the function will be called by your LDAP client. Code Example 16-15 illustrates the prototype.
Code Example 16-15 LDAP_IOF_CLOSE_CONNECT_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_IOF_CLOSE_CALLBACK )( LBER_SOCKET );
LDAP_IOF_CONNECT_CALLBACKLDAP_IOF_CONNECT_CALLBACK specifies the prototype for a callback function equivalent to the standard connect() network I/O function.
Description
If you define a function with this prototype and set it in the ldap_io_fns structure, the function will be called by your LDAP client. Code Example 16-16 is the prototype.
Code Example 16-16 LDAP_IOF_CONNECT_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_IOF_CONNECT_CALLBACK )( LBER_SOCKET,
struct sockaddr *, int );
LDAP_IOF_IOCTL_CALLBACKLDAP_IOF_IOCTL_CALLBACK specifies the prototype for a callback function equivalent to the standard ioctl() system call.
Description
If you define a function with this prototype and set it in the ldap_io_fns structure, the function will be called by your LDAP client. Code Example 16-17 is the prototype.
Code Example 16-17 LDAP_IOF_IOCTL_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_IOF_IOCTL_CALLBACK)( LBER_SOCKET, int, ... );
LDAP_IOF_READ_CALLBACKLDAP_IOF_READ_CALLBACK specifies the prototype for a callback function equivalent to the standard read() I/O function.
Description
If you define a function with this prototype and set it in the ldap_io_fns structure, the function will be called by your LDAP client. Code Example 16-18 is the prototype.
Code Example 16-18 LDAP_IOF_READ_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_IOF_READ_CALLBACK)( LBER_SOCKET, void *, int );
LDAP_IOF_SELECT_CALLBACKLDAP_IOF_SELECT_CALLBACK specifies the prototype for a callback function equivalent to the standard select() I/O function.
Description
If you define a function with this prototype and set it in the ldap_io_fns structure, the function will be called by your LDAP client. Code Example 16-19 is the prototype.
Code Example 16-19 LDAP_IOF_SELECT_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_IOF_SELECT_CALLBACK)( int, fd_set *, fd_set *,
fd_set *, struct timeval * );
LDAP_IOF_SOCKET_CALLBACKLDAP_IOF_SOCKET_CALLBACK specifies the prototype for a callback function equivalent to the standard socket() network I/O function.
Description
If you define a function with this prototype and set it in the ldap_io_fns structure, the function will be called by your LDAP client. Code Example 16-20 is the prototype.
Code Example 16-20 LDAP_IOF_SOCKET_CALLBACK Prototype
typedef LBER_SOCKET (LDAP_C LDAP_CALLBACK
LDAP_IOF_SOCKET_CALLBACK)( int, int, int );
LDAP_IOF_SSL_ENABLE_CALLBACKLDAP_IOF_SSL_ENABLE_CALLBACK specifies the prototype for a callback function equivalent to the ssl_enable() function.
Description
If you define a function with this prototype and set it in the ldap_io_fns structure, the function will be called by your LDAP client. Code Example 16-21 is the prototype.
Code Example 16-21 LDAP_IOF_SSL_ENABLE_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_IOF_SSL_ENABLE_CALLBACK )( LBER_SOCKET );
LDAP_IOF_WRITE_CALLBACKLDAP_IOF_WRITE_CALLBACK specifies the prototype for a callback function equivalent to the standard write() I/O function.
Description
If you define a function with this prototype and set it in the ldap_io_fns structure, the function will be called by your LDAP client. Code Example 16-22 is the prototype.
Code Example 16-22 LDAP_IOF_WRITE_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK LDAP_IOF_WRITE_CALLBACK)
( LBER_SOCKET, const void *, int );
ldap_io_fnsThe ldap_io_fns structure contains a set of pointers to input/output functions that you want used with SDK. You need to set up this structure if you want to connect to the LDAP server using a Secure Sockets Layer (SSL). Code Example 16-23 illustrates the definition of the ldap_io_fns structure.
Code Example 16-23 ldap_io_fns Structure
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;
};
Table 16-20 defines the fields in this structure.
Table 16-20 ldap_io_fns Field Descriptions
Field
What It Contains
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.
LDAP_KEYCMP_CALLBACKLDAP_KEYCMP_CALLBACK specifies the prototype for a callback function to sort a specified set of entries.
Definition
If you define a function with this prototype and specify it when calling ldap_keysort_entries(), the function will be called by your LDAP client to sort a specified set of entries.
See Also
LDAP_KEYFREE_CALLBACKLDAP_KEYFREE_CALLBACK specifies the prototype for a callback function that frees a sorting key.
Description
ldap_keysort_entries() requires a function pointer that matches the signature defined by this type.
LDAP_KEYGEN_CALLBACKLDAP_KEYGEN_CALLBACK specifies the prototype for a callback function that generates a key for sorting.
Description
ldap_keysort_entries() requires a function pointer that matches the signature defined by this type.
LDAP_MALLOC_CALLBACKThis callback function prototype of ldap_memalloc_fns represents memory allocation.
See Also
ldap_memalloc_fnsldap_memalloc_fns is a structure representing callback functions for memory allocation. These are global and can not be set on a per-LDAP session handle basis. Install your own functions by making a call similar to the one detailed in Code Example 16-24.
Code Example 16-24 Installing ldap_memalloc_fns
ldap_set_option( NULL, LDAP_OPT_MEMALLOC_FN_PTRS, &memalloc_fns )
See Also
LDAPMemCacheLDAPMemCache is a type of structure representing an in-memory, client-side cache. You can create a cache and specify the following information:
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
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 result of that search. If you send a similar search request specifying that you want to retrieve all attributes instead of just the uid, the result cached from the previous search are not used.
The cache uses a combination of the following information as the key to a cached item:
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.
Related Functions
Table 16-21 lists functions related to the LDAPMemCache structure.
Table 16-21 Functions for LDAPMemCache Structure
Function
Description
Creates an LDAPMemCache structure and initialize the caching mechanism.
Associates an LDAPMemCache structure with a connection handle (an LDAP structure).
Returns the LDAPMemCache structure that is associated with a connection handle (an LDAP structure).
Forces the cache to remove expired items.
Removes entries from the cache.
Frees the memory used by the cache and frees the LDAPMemCache structure.
LDAPMessageLDAPMessage is a structure representing the results of an LDAP operation, i.e.: a chain of search results, an entry in the search results, or a search reference in the search results.
Note
LDAPMessage is not completely defined in ldap.h because the fields within the structure are not intended to be directly accessible to clients.
Description
Calling the ldap_search_ext_s() or ldap_search_ext() followed by the ldap_result() function creates an LDAPMessage structure to represent the chain of results from the 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.
LDAPModLDAPMod is a structure that you use to specify changes to an attribute in a directory entry.
Description
Before you call the ldap_add_ext(), ldap_add_ext_s(), ldap_modify_ext(), or ldap_modify_ext_s() functions 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. Code Example 16-25 illustrates the LDAPMod definition.
Code Example 16-25 LDAPMod Definition
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;
Table 16-22 defines the fields in this structure.
Table 16-22 LDAPMod Field Descriptions
Field
What It Contains
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:
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 the following caveats when defining :
- If you specify LDAP_MOD_DELETE and remove all values in an attribute, the attribute is removed from the entry.
- If you specify LDAP_MOD_DELETE and NULL in the mod_values field, the attribute is removed from the entry.
- If you specify LDAP_MOD_REPLACE and NULL in the mod_values field, the attribute is removed from the entry.
- If you specify LDAP_MOD_REPLACE and the attribute does not exist in the entry, the attribute is added to the entry.
- If you specify LDAP_MOD_ADD and the attribute does not exist in the entry, the attribute is added to the entry.
Also, 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 an Entry" of Chapter 7, "Adding, Modifying and Deleting Entries" 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’ve allocated memory for the structures yourself, you should free them when finished by calling the ldap_mods_free() function.
Example
Code Example 16-26 sets up an LDAPMod structure to change the email address of a user’s entry to bjensen@example.com.
Code Example 16-26 Setting Up an LDAPMod Structure
LDAP *ld;
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_REALLOC_CALLBACKThis callback function prototype of ldap_memalloc_fns represents memory allocation.
See Also
LDAP_REBINDPROC_CALLBACKLDAP_REBINDPROC_CALLBACK specifies the prototype for a callback function that retrieves authentication information when automatically following referrals to other servers.
Description
If you define a function with this prototype and specify it when calling the ldap_set_rebind_proc() function, the function will be called by your LDAP client. Code Example 16-27 is the prototype.
Code Example 16-27 LDAP_REBINDPROC_CALLBACK Prototype
typedef int (LDAP_CALL LDAP_CALLBACK
LDAP_REBINDPROC_CALLBACK)( LDAP *ld, char **dnp, char **passwdp,
int *authmethodp, int freeit, void *arg);
See Also
LDAPsortkeyLDAPsortkey represents the criteria to be used by a server control to sort search results before sending the results back to the client.
Note
Controls are part of the LDAPv3 and are used to extend the functionality of an LDAP operation. The two types of controls described in the LDAPv3 are:
- 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. See "Using the Server-Side Sorting Control" of Chapter 13, "Working with LDAP Controls" for more information.
- 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. Sun Java System LDAP SDK for C does not currently support any client controls.
Description
Code Example 16-28 illustrates how LDAPsortkey is defined.
Code Example 16-28 LDAPsortkey Definition
typedef struct LDAPsortkey {
char *sk_attrtype;
char *sk_matchruleoid;
int sk_reverseorder;
} LDAPsortkey;
Table 16-23 defines the fields in this structure.
Table 16-23 LDAPsortkey Field Descriptions
Field
What It Contains
sk_attrtype
Pointer to a NULL-terminated string that specifies the name of the attribute that you want to use for sorting.
sk_matchruleoid
Pointer to a NULL-terminated string that specifies the 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:
As an example, you can use LDAPsortkey to specify that you want the server to sort search results by the roomNumber attribute. 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_CALLBACKLDAP_TF_GET_ERRNO_CALLBACK specifies the prototype for a callback function to get the value of the errno variable for a thread.
Note
For more details on the errno variable, see ldap_thread_fns.
Description
Code Example 16-29 is the prototype specified by this data type.
Code Example 16-29 LDAP_TF_GET_ERRNO_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_TF_GET_ERRNO_CALLBACK) ( void );
LDAP_TF_GET_LDERRNO_CALLBACKLDAP_TF_GET_LDERRNO_CALLBACK specifies the prototype for a callback function to retrieve the LDAP result code for an operation.
Description
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().
Note
For more details on the arguments and return values that your function must use, see ldap_get_lderrno().
Code Example 16-30 is the prototype for this data type.
Code Example 16-30 LDAP_TF_GET_LDERRNO_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_TF_GET_LDERRNO_CALLBACK)( char **, char **, void * );
LDAP_TF_SET_ERRNO_CALLBACKLDAP_TF_SET_ERRNO_CALLBACK specifies the prototype for a callback function to set the value of the errno variable for a thread.
Note
For more details on the errno variable, see ldap_thread_fns.
Description
Code Example 16-31 is the prototype for this data type.
Code Example 16-31 LDAP_TF_SET_ERRNO_CALLBACK Prototype
typedef void (LDAP_C LDAP_CALLBACK
LDAP_TF_SET_ERRNO_CALLBACK)( int );
LDAP_TF_SET_LDERRNO_CALLBACKLDAP_TF_SET_LDERRNO_CALLBACK specifies the prototype for a callback function to set the LDAP result code for an operation.
Note
For more details on the arguments that your function must use, see ldap_set_lderrno().
Description
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. Code Example 16-32 is the prototype specified by this data type.
Code Example 16-32 LDAP_TF_SET_LDERRNO_CALLBACK Prototype
typedef void (LDAP_C LDAP_CALLBACK
LDAP_TF_SET_LDERRNO_CALLBACK)( int, char *, char *, void * );
LDAP_TF_MUTEX_ALLOC_CALLBACKLDAP_TF_MUTEX_ALLOC_CALLBACK specifies the prototype for a callback function to allocate a mutex.
Description
Code Example 16-33 is the prototype specified by this data type.
Code Example 16-33 LDAP_TF_MUTEX_ALLOC_CALLBACK Prototype
typedef void *(LDAP_C LDAP_CALLBACK
LDAP_TF_MUTEX_ALLOC_CALLBACK)( void );
See Also
LDAP_TF_MUTEX_FREE_CALLBACKLDAP_TF_MUTEX_FREE_CALLBACK specifies the prototype for a callback function to free a mutex.
Description
Code Example 16-34 is the prototype specified by this data type.
Code Example 16-34 LDAP_TF_MUTEX_FREE_CALLBACK Prototype
typedef void (LDAP_C LDAP_CALLBACK
LDAP_TF_MUTEX_FREE_CALLBACK)( void * );
See Also
LDAP_TF_MUTEX_LOCK_CALLBACKLDAP_TF_MUTEX_LOCK_CALLBACK specifies the prototype for a callback function to lock a mutex.
Description
Code Example 16-35 is the prototype specified by this data type.
Code Example 16-35 LDAP_TF_MUTEX_LOCK_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_TF_MUTEX_LOCK_CALLBACK)( void * );
See Also
LDAP_TF_MUTEX_TRYLOCK_CALLBACKThis function prototype is not supported in this release of the LDAP SDK for C.
LDAP_TF_MUTEX_UNLOCK_CALLBACKLDAP_TF_MUTEX_UNLOCK_CALLBACK specifies the prototype for a callback function to unlock a mutex.
Description
Code Example 16-36 is the prototype specified by this data type.
Code Example 16-36 LDAP_TF_MUTEX_UNLOCK_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_TF_MUTEX_UNLOCK_CALLBACK)( void * );
See Also
LDAP_TF_SEMA_ALLOC_CALLBACKThis function prototype is not supported in this release of the LDAP SDK for C.
LDAP_TF_SEMA_FREE_CALLBACKThis function prototype is not supported in this release of the LDAP SDK for C.
LDAP_TF_SEMA_POST_CALLBACKThis function prototype is not supported in this release of the LDAP SDK for C.
LDAP_TF_SEMA_WAIT_CALLBACKThis function prototype is not supported in this release of the LDAP SDK for C.
LDAP_TF_THREADID_CALLBACKLDAP_TF_THREADID_CALLBACK specifies the prototype for a callback function to return an identifier that is unique to the calling thread, much like the POSIX pthread_self() function does.
Description
Code Example 16-37 is the prototype specified by this data type.
Code Example 16-37 LDAP_TF_THREADID_CALLBACK Prototype
typedef void *(LDAP_C LDAP_CALLBACK
LDAP_TF_THREADID_CALLBACK)( void );
See Also
ldap_thread_fnsThe ldap_thread_fns structure contains a set of pointers to functions that you want to use when write a multithreaded client.
Description
Code Example 16-38 is the definition of the ldap_thread_fns structure.
Code Example 16-38 ldap_thread_fns Structure Definition
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;
};
Table 16-24 defines the fields in this structure.
Table 16-24 ldap_thread_fns Field Descriptions
Field
What It Contains
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 at compile time so that it has a value for each thread, rather than a global value for the entire process. 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. 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 at compile time so that it has a value for each thread, rather than a global value for the entire process. 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. 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.
Example
For an example of setting up the ldap_thread_fns structure, see Chapter 14, "Writing Multithreaded Clients."
LDAPURLDescLDAPURLDesc is a structure that represents the components of an LDAP URL.
Description
LDAP URLs have the following syntax:
ldap://host:port/dn?attributes?scope?(filter)
Where, for example:
ldap://ldap.itd.umich.edu/c=US?o,description?one?(o=umich)
Calling the ldap_url_parse() function creates an LDAPURLDesc structure with the components of the URL. Code Example 16-39 is the LDAPURLDesc definition.
Code Example 16-39 LDAPURLDesc Definition
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;
Table 16-25 describes the fields in this structure.
Table 16-25 LDAPURLDesc Field Descriptions
Field
What It Contains
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:
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.iplanet.com:5000/dc=example,dc=com?cn,mail, \
telephoneNumber?sub?(sn=Jensen)
The resulting LDAPURLDesc structure (ludpp, in this example) will contain the values in Table 16-26.
Table 16-26 LDAPURLDesc Parsed URL Values
Component
Value
ludpp->lud_host
ldap.iplanet.com
ludpp->lud_port
5000
ludpp->lud_dn
dc=example,dc=com
ludpp->lud_attrs[0]
cn
ludpp->lud_attrs[1]
ludpp->lud_attrs[2]
telephoneNumber
ludpp->lud_attrs[3]
NULL
ludpp->lud_scope
LDAP_SCOPE_SUBTREE
ludpp->lud_filter
(sn=Jensen)
To free the LDAPURLDesc structure, call the ldap_free_urldesc() routine.
LDAP_VALCMP_CALLBACKLDAP_VALCMP_CALLBACK specifies the prototype for a callback function to sort a specified set of values.
Description
If you define a function with this prototype and specify it when calling the ldap_sort_strcasecmp() function, the function will be called by your LDAP client. Code Example 16-40 is the prototype.
Code Example 16-40 LDAP_VALCMP_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK
LDAP_VALCMP_CALLBACK)(const char**, const char**);
ldap_sort_values() requires a function pointer that matches the signature defined by this type. ldap_sort_strcasecmp() is a value comparison function defined using this type which can therefore be passed to ldap_sort_values().
See Also
ldap_sort_values(), ldap_sort_strcasecmp()
LDAPVersionThe LDAPVersion structure contains version information about the LDAP SDK for C.
Caution
The LDAPVersion type is deprecated; it is documented here only for backward compatibility. Instead, use the ldap_get_option() function with the LDAP_OPT_API_INFO option and retrieve an LDAPAPIInfo structure.
Description
Call the ldap_version() function to return a pointer to an LDAPVersion structure containing version information. Code Example 16-41 is the definition for LDAPVersion.
Code Example 16-41 LDAPVersion Definition
typedef struct _LDAPVersion {
int sdk_version;
int protocol_version;
int SSL_version;
int security_level;
} LDAPVersion;
Table 16-27 describes the fields in this structure.
Table 16-27 LDAPVersion Field Definitions
Field
What It Contains
sdk_version
Version number of the LDAP SDK for C 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.
LDAPVirtualListLDAPVirtualList specifies the information that can be used to create a virtual list view control.
Description
A virtual list view control is a LDAPv3 control designed to allow the client to retrieve subsets of search results to display in a virtual list box. A virtual list box is typically a graphical user interface that displays a long list of entries with a few entries visible. To display the list, 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. (For more information, see "Using the Virtual List View Control" of Chapter 13, "Working with LDAP Controls.")
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. End users can display different sections of the list by scrolling up or down.
Note
The object identifier (OID) for this control is OID 2.16.840.1.113730.3.4.9, or LDAP_CONTROL_VLVREQUEST as defined in ldap.h. It is supported by Sun Java System Directory Server. For information on determining if your server supports this or other LDAPv3 controls, see "Determining Supported Controls" of Chapter 13, "Working with LDAP Controls."
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 currently selected entry can be identified in one of the following ways:
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:
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:
Code Example 16-42 illustrates the LDAPVirtualList definition.
Code Example 16-42 LDAPVirtualList Definition
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;
Table 16-28 describes the fields in this structure.
Table 16-28 LDAPVirtualList Field Descriptions
Field
What It Contains
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. This data is not used in the virtual list view control.
LDAP_X_EXTIOF_CLOSE_CALLBACKThis specifies the prototype for an extended I/O callback function to close a socket connection.
Description
Code Example 16-43 is the prototype.
Code Example 16-43 LDAP_X_EXTIOF_CLOSE_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_CLOSE_CALLBACK )(
int s, void *arg );
See Also
LDAP_X_EXTIOF_CONNECT_CALLBACKThis specifies the prototype for an extended I/O callback function to open a socket connection.
Description
LDAP_X_EXTIOF_CONNECT_CALLBACK takes a timeout parameter whose value (in milliseconds) can be set by calling ldap_set_option(). Code Example 16-44 is the protoype.
Code Example 16-44 LDAP_X_EXTIOF_CONNECT_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_CONNECT_CALLBACK )(
int s, LDAP_X_SockAddr *saddr, int saddr_len,
int timeout /* milliseconds */, void *arg );
See Also
LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACKThis specifies the prototype for an extended I/O callback function to dispose of a session handle.
Description
LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK is called right before the LDAP session handle and its contents are destroyed (during ldap_unbind()). The value of the arg parameter passed to the callback is always the default one. Code Example 16-44 is the protoype.
Code Example 16-45 LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK Prototype
typedef void (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK)(
LDAP *ld, void *arg );
See Also
LDAP_X_EXTIOF_NEWHANDLE_CALLBACKThis specifies the prototype for an extended I/O callback function to define a new session handle.
Description
LDAP_X_EXTIOF_NEWHANDLE_CALLBACK is called right after the LDAP session handle is created (during ldap_init()). The value of the arg parameter passed to the callback is always the default one. If the callback returns anything other than LDAP_SUCCESS, the session handle allocation fails. Code Example 16-46 is the prototype.
Code Example 16-46 LDAP_X_EXTIOF NEWHANDLE_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_NEWHANDLE_CALLBACK)(
LDAP *ld, void *arg );
See Also
ldap_x_ext_io_fnsThis is a structure to hold extended I/O function pointers. Code Example 16-47 is the definition.
Code Example 16-47 ldap_x_ext_io_fns Definition
struct ldap_x_ext_io_fns {
/* lextiof_size should always be set to LDAP_X_EXTIO_FNS_SIZE */
int lextiof_size;
LDAP_X_EXTIOF_CONNECT_CALLBACK *lextiof_connect;
LDAP_X_EXTIOF_CLOSE_CALLBACK *lextiof_close;
LDAP_X_EXTIOF_READ_CALLBACK *lextiof_read;
LDAP_X_EXTIOF_WRITE_CALLBACK *lextiof_write;
LDAP_X_EXTIOF_POLL_CALLBACK *lextiof_poll;
LDAP_X_EXTIOF_NEWHANDLE_CALLBACK *lextiof_newhandle;
LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK *lextiof_disposehandle;
void *lextiof_session_arg;
LDAP_X_EXTIOF_WRITEV_CALLBACK *lextiof_writev;
};
#define LDAP_X_EXTIO_FNS_SIZE sizeof(struct ldap_x_ext_io_fns)
LDAP_X_EXTIOF_POLL_CALLBACKThis specifies the prototype for an extended I/O callback function to close a socket connection.
Description
The LDAP_X_EXTIOF_POLL_CALLBACK interface is provided instead of a standard select() interface. The timeout is in milliseconds. The value of the arg parameter passed to the callback is always the default one. Code Example 16-48 is the prototype.
Code Example 16-48 LDAP_X_EXTIOF_POLL_CALLBACK Prototype
typedef int (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_POLL_CALLBACK)(
LDAP_X_PollFD fds[], int nfds, int timeout /* milliseconds */,
void *arg );
See Also
ldap_x_ext_io_fns, LDAP_X_PollFD
ldap_x_hostlist_statusThis structure contains utility functions for parsing space-separated host lists.
Description
Code Example 16-49 is the definition of this structure.
Code Example 16-49 ldap_x_hostlist_status Definition
struct ldap_x_hostlist_status;
LDAP_API(int) LDAP_CALL ldap_x_hostlist_first( const char *hostlist,
int defport, char **hostp, int *portp /* host byte order */,
struct ldap_x_hostlist_status **statusp );
LDAP_API(int) LDAP_CALL ldap_x_hostlist_next( char **hostp,
int *portp /* host byte order */, struct ldap_x_hostlist_status *status
);
LDAP_API(void) LDAP_CALL ldap_x_hostlist_statusfree(
struct ldap_x_hostlist_status *status );
LDAP_X_PollFDThis is a structure to hold the set of file descriptors that will be surveyed for I/O by the LDAP_X_EXTIOF_POLL_CALLBACK.
Description
Code Example 16-50 is the definition of the structure.
Code Example 16-50 LDAP_X_PollFD Structure Definition
typedef struct ldap_x_pollfd { /* used by LDAP_X_EXTIOF_POLL_CALLBACK */
int lpoll_fd; /* integer file descriptor / socket */
void *lpoll_arg; /* pointer socket and for use by application */
short lpoll_events; /* requested event */
short lpoll_revents; /* returned event */
} LDAP_X_PollFD;
