Mozilla LDAP SDK Programmer's Guide/LDAP C SDK Data Type Reference

This section contains reference material for the public data types and structures of LDAP C SDK. The first subsections detail the data types of the grouped into task categories. The last subsection is an alphabetical listing of the same information.

Conventions

The following sections detail certain conventions and concepts used in LDAP C SDK.

Typographical Conventions

The following table lists the typographical conventions used in the names of data types and structures.

Typographical Conventions in Data Types and Structures
Convention	Description of Use
`LeadingCaps`	Data structures needed to pass values to and from functions of LDAP C SDK. For consistency, use this `typedef` name for these structures, not their literal `struct` name.
`ALL_CAPS`	Names of callback function prototypes which you can implement for extended functionality in your client application.
`fns suffix`	Structures which hold the function pointers for callback functions, grouped by task.

Deprecated Structures

A deprecated API is one you should no longer use for new development, and should begin to phase out for applications you maintain. Deprecated interfaces may disappear in the major version following their deprecation.

Structure Summary by Task

In the following sections the structures defined by LDAP C SDK are grouped into task categories.

BER Structures

The structures listed in the following table 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 LDAP C SDK.

BER Structures
Structure	Description
berval	berval represents binary data encoded using BER.
BerElement	BerElement indicates the current position during a traversal of an attribute list.

Structures for the Core API

The structures listed in the following table are used by the core functions of LDAP C SDK. These structures are used directly as argument or return types by functions that provide the core functionality.

Core API Structures
Structure	Description
LDAP	LDAP represents a connection handle to the LDAP server.
LDAPMessage	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	LDAPMod specifies changes to an attribute in an directory entry.
LDAPControl	LDAPControl represents a client or server control associated with an LDAP operation.
LDAPAPIInfo	LDAPAPIInfo represents information about the version of LDAP C SDK being implemented
LDAPAPIFeatureInfo	LDAPAPIFeatureInfo represents information about the extended features.

Structures for API Extensions

The structures listed in the following table are needed for extensions to the standard API within LDAP C SDK. These structures are used directly as arguments or return types by the functions that provide the extended functionality.

API Extension Structures
Structure	Description
LDAPsortkey	LDAPsortkey represents a server control used to specify that the server should sort the search results before sending them back to the client.
LDAPVirtualList	LDAPVirtualList specifies the information that can be used to create a virtual list view control.
LDAPURLDesc	LDAPURLDesc represents the components of an LDAP URL.
LDAPFiltInfo	LDAPFiltInfo represents information about a filter in a filter configuration file.
LDAPFiltDesc	LDAPFiltDesc is a type of structure returned when you call ldap_init_getfilter to load a filter configuration file.
FriendlyMap	FriendlyMap represents the mapping between a list of standard attribute names and their user friendly counterparts.
LDAPMemCache	LDAPMemCache represents an in-memory, client-side cache.
LDAPpwdpolicy	LDAPpwdpolicy represents password policy information concerning an entry.
LDAPuserstatus	LDAPuserstatus represents account availability information.

Note: This prototype for a callback function retrieves authentication information when automatically following referrals to other servers.

Referral Binding Data Type
Data Type	Description
LDAP_REBINDPROC_CALLBACK	Retrieves authentication information when following referrals to other servers.

Client-Side Sorting Callbacks

The prototype structures listed in the following table are extensions to LDAP C SDK that implement client side sorting of entries.

Client-side Sorting Structures
Data Type	Description
LDAP_KEYGEN_CALLBACK	Function prototype that generates the sorting key for each entry to be sorted, usually by extracting a value out of an entry.
LDAP_KEYCMP_CALLBACK	Function prototype to compare 2 keys (for ordering).
LDAP_KEYFREE_CALLBACK	Function prototype that frees the memory allocated during the `KEYGEN` callback.
LDAP_CMP_CALLBACK	Function prototype to sort a specified set of entries.
LDAP_VALCMP_CALLBACK	Function prototype to sort a specified set of values.

Extended I/O Control

The following table lists the prototypes and structures used in the extended I/O control, an extension to the standard API.

Structures and Prototypes for Extended I/O Functionality
Data Type	Description
ldap_x_ext_io_fns	This structure holds extended I/O function pointers.
LDAP_X_PollFD	An LDAP file descriptor similar to that of poll().
LDAP_X_EXTIOF_CONNECT_CALLBACK	Function prototype for a callback that opens a socket connection.
LDAP_X_EXTIOF_CLOSE_CALLBACK	Function prototype for a callback that closes a socket connection.
LDAP_X_EXTIOF_POLL_CALLBACK	Function prototype for a callback that surveys a server about a particular event.
LDAP_X_EXTIOF_NEWHANDLE_CALLBACK	Function prototype for a callback that defines a new session handle.
LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK	Function prototype for a callback that disposes of a session handle.
ldap_x_hostlist_status	This structure holds utility functions for parsing space-separated host lists.

Memory Management Control

The prototypes and structures listed in theh following table are used in memory management control, an extension to the standard API. They allow you to specify your own memory allocation mechanisms and functions.

Memory Management Data Types
Data Type	Description
ldap_memalloc_fns	This structure holds the memory allocation callback functions.
LDAP_MALLOC_CALLBACK LDAP_CALLOC_CALLBACKLDAP_REALLOC_CALLBACK LDAP_FREE_CALLBACK	These callbacks allow developers to specify their own memory allocation mechanisms.

Thread Signaling Controls

The prototypes and structures listed in the following table are used in the thread signaling control, an extension to the standard API.

Thread Signaling Control Data Types
Data Type	Description
ldap_thread_fns	Structure that contains a set of pointers to functions you want to use when writing a multithreaded client.
LDAP_TF_MUTEX_ALLOC_CALLBACK	Function prototype for allocating a mutex.
LDAP_TF_MUTEX_FREE_CALLBACK	Function prototype freeing a mutex.
LDAP_TF_MUTEX_LOCK_CALLBACK	Function prototype for locking critical sections of code.
LDAP_TF_MUTEX_UNLOCK_CALLBACK	Function prototype for unlocking critical sections of code.
LDAP_TF_GET_ERRNO_CALLBACK	Function prototype for getting the value of the `errno` variable.
LDAP_TF_SET_ERRNO_CALLBACK	Function prototype for setting the value of the `errno` variable.
LDAP_TF_GET_LDERRNO_CALLBACK	Function prototype for getting error values from calls to functions in the `libldap` library.
LDAP_TF_SET_LDERRNO_CALLBACK	Function prototype for setting error values from calls to functions in the `libldap` library.
ldap_extra_thread_fns	Structure that contains a set of pointers to additional functions you want to use when writing a multithreaded client.
LDAP_TF_MUTEX_TRYLOCK_CALLBACK	Function prototype for attempting to lock a mutex.
LDAP_TF_SEMA_ALLOC_CALLBACK	Function prototype for allocating a semaphore.
LDAP_TF_SEMA_FREE_CALLBACK	Function prototype for freeing a semaphore.
LDAP_TF_SEMA_WAIT_CALLBACK	Function prototype for waiting for the value of a semaphore to be greater than 0.
LDAP_TF_SEMA_POST_CALLBACK	Function prototype for incrementing the value of a semaphore.
LDAP_TF_THREADID_CALLBACK	Function prototype to return an identifier that is unique to the calling thread.

Deprecated and Outdated Types

Deprecated types are those being dropped from the standard or from the extensions to LDAP C SDK. 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. The following table lists the deprecated prototypes.

Deprecated Data Types and Their Replacements
Data Type	Replacement
LDAP_CANCELPROC_CALLBACK	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_CALLBACK	ldap_cache_fns is a deprecated structure and the `typedef` declarations associated with it have also been deprecated.
LDAPVersion	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 superseded by new types. Outdated types may become deprecated in future releases of LDAP C SDK. The following table lists the outdated types and the newer types which implement the same functionality.

Outdated Types and Their New Equivalents
Old Data Type	New, Equivalent Data Type
LDAPHostEnt LDAP_DNSFN_GETHOSTBYNAME LDAP_DNSFN_GETHOSTBYADDR ldap_dns_fns	The 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_fns	Replaced by the types for extended I/O functionality detailed in the section on Extended I/O Control.

Structures Alphabetically

The following sections detail the structures and controls of LDAP C SDK in alphabetical order.

berval

berval 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.

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

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.

BerElement

The 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 attribute 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.

FriendlyMap

FriendlyMap 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:

ldap_friendly_name allocates() a FriendlyMap structure and reads a list of standard attribute names and their user friendly counterparts from a file.
ldap_free_friendlymap() frees the memory allocated for a FriendlyMap structure.

LDAP

LDAP 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.

Note: LDAP is not completely defined in ldap-standard.h because the fields within the structure are not intended to be accessible to clients.

LDAPAPIFeatureInfo

LDAPAPIFeatureInfo is a structure that represents information about the extended features of LDAP C SDK. <title>LDAPAPIFeatureInfo Definition

#define LDAP_FEATURE_INFO_VERSION
typedef struct ldap_apifeature_info {
  int   ldapaif_info_version;       /* version of this struct (1) */
  char  *ldapaif_name;              /* name of supported feature */
  int   ldapaif_version;            /* revision of supported feature */
} LDAPAPIFeatureInfo;

The LDAPAPIFeatureInfo structure can be retrieved by using a sequence like the one displayed below.

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

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.

LDAPAPIInfo

LDAPAPIInfo is a structure that represents information about the API and supported extensions.

#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 x 100 */
} LDAPAPIInfo;

The LDAPAPIInfo structure can be retrieved by using a sequence like the one displayed in the following example.

LDAPAPIInfo ldai;
ldai.ldapai_info_version = LDAP_API_INFO_VERSION;
if ( ldap_get_option( NULL, LDAP_OPT_API_INFO, &ldia ) == 0 ) ...

Parameters

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_fns

ldap_cache_fns is a deprecated structure. The following are also deprecated:

LDAP_CF_ADD_CALLBACK
LDAP_CF_BIND_CALLBACK
LDAP_CF_COMPARE_CALLBACK
LDAP_CF_DELETE_CALLBACK
LDAP_CF_FLUSH_CALLBACK
LDAP_CF_MODIFY_CALLBACK
LDAP_CF_MODRDN_CALLBACK
LDAP_CF_RESULT_CALLBACK
LDAP_CF_SEARCH_CALLBACK
LDAP_CF_UNBIND_CALLBACK

See Also

See the ldap_memcache_*() functions for current usage.

LDAP_CALLOC_CALLBACK

This callback function prototype of ldap_memalloc_fns() represents memory allocation.

See Also

ldap_memalloc_fns

LDAP_CANCELPROC_CALLBACK

This callback function prototype is deprecated.

See Also

ldap_ufn_search_c, ldap_ufn_search_ct