<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="bdajr"><title>&DirectorySDKForC; Data Type Reference</title>
<indexterm>
<primary>C SDK data types</primary>
</indexterm><indexterm>
<primary>data types</primary>
<see>C SDK data types</see></indexterm><highlights>
<para>This chapter contains reference material for the public data types and
structures of &DirectorySDKForC;. 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:</para>
<itemizedlist>
<listitem><para><olink targetptr="bdajs">Conventions</olink></para></listitem>
<listitem><para><olink targetptr="bdajv">Structure Summary by Task</olink></para>
</listitem>
<listitem><para><olink targetptr="bdakf">Structures Alphabetically</olink></para>
</listitem>
</itemizedlist>
</highlights>
<sect1 id="bdajs"><title>Conventions</title>
<para>The following sections detail certain conventions and concepts used
in &DirectorySDKForC;.</para>
<sect2 id="bdajt"><title>Typographical Conventions</title>
<indexterm>
<primary>C SDK data types</primary>
<secondary>typographical conventions</secondary>
</indexterm>
<para><olink targetptr="csdk-typographical">Table 20&ndash;1</olink> lists
the typographical conventions used in the names of data types and structures.</para>
<table frame="topbot" id="csdk-typographical"><title>Typographical Conventions
in Data Types and Structures</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Convention</para></entry>
<entry>
<para>Description of Use</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>LeadingCaps</literal></para></entry>
<entry>
<para>Data structures needed to pass values to and from functions of &DirectorySDKForC;.
For consistency, use this <literal>typedef</literal> name for these structures,
not their literal <literal>struct</literal> name.</para></entry>
</row>
<row>
<entry>
<para><literal>ALL_CAPS</literal></para></entry>
<entry>
<para>Names of callback function prototypes which you can implement for extended
functionality in your client application.</para></entry>
</row>
<row>
<entry>
<para><literal>fns  suffix</literal></para></entry>
<entry>
<para>Structures which hold the function pointers for callback functions,
grouped by task.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdaju"><title>Deprecated Structures</title>
<indexterm>
<primary>C SDK data types</primary>
<secondary>deprecated</secondary>
</indexterm>
<para>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.</para></sect2>
</sect1>
<sect1 id="bdajv"><title>Structure Summary by Task</title>
<indexterm>
<primary>C SDK data types</primary>
<secondary>summary by task</secondary>
</indexterm>
<para>In the following sections the structures defined by &DirectorySDKForC;
are grouped into task categories.</para>
<sect2 id="bdajw"><title>BER Structures</title>
<para>The structures listed in <olink targetptr="ber-structures">Table 20&ndash;2
</olink> represent data encoded using the Basic Encoding Rules (BER). The <literal>
lber.h</literal> 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 &DirectorySDKForC;.</para>
<table frame="topbot" id="ber-structures"><title>BER Structures</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Structure</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdakg">berval</olink></para></entry>
<entry>
<para><olink targetptr="bdakg">berval</olink> represents binary data encoded
using BER.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdakh">BerElement</olink></para></entry>
<entry>
<para><olink targetptr="bdakh">BerElement</olink> indicates the current position
during a traversal of an attribute list.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdajx"><title>Structures for the Core API</title>
<indexterm>
<primary>C SDK data types</primary>
<secondary>summary by task</secondary>
</indexterm>
<para>The structures listed in <olink targetptr="core-api-structures">Table
20&ndash;3</olink>  are used by the core functions of &DirectorySDKForC;.
These structures are used directly as argument or return types by functions
that provide the core functionality.</para>
<table frame="topbot" id="core-api-structures"><title>Core API Structures</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Structure</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdakj">LDAP</olink></para></entry>
<entry>
<para><olink targetptr="bdakj">LDAP</olink> represents a connection handle
to the LDAP server.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaly">LDAPMessage</olink></para></entry>
<entry>
<para><olink targetptr="bdaly">LDAPMessage</olink> 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.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdalz">LDAPMod</olink></para></entry>
<entry>
<para><olink targetptr="bdalz">LDAPMod</olink> specifies changes to an attribute
in an directory entry.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdala">LDAPControl</olink></para></entry>
<entry>
<para><olink targetptr="bdala">LDAPControl</olink> represents a client or
server control associated with an LDAP operation.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdakl">LDAPAPIInfo</olink></para></entry>
<entry>
<para><olink targetptr="bdakl">LDAPAPIInfo</olink> represents information
about the version of &DirectorySDKForC; being implemented</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdakk">LDAPAPIFeatureInfo</olink></para></entry>
<entry>
<para><olink targetptr="bdakk">LDAPAPIFeatureInfo</olink> represents information
about the extended features.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdajy"><title>Structures for API Extensions</title>
<para>The structures listed in <olink targetptr="api-extension-structures">Table
20&ndash;4</olink>  are needed for extensions to the standard API within &DirectorySDKForC;.
These structures are used directly as arguments or return types by the functions
that provide the extended functionality.</para>
<table frame="topbot" id="api-extension-structures"><title>API Extension Structures
</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Structure</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdamc">LDAPsortkey</olink></para></entry>
<entry>
<para><olink targetptr="bdamc">LDAPsortkey</olink> represents a server control
used to specify that the server should sort the search results before sending
them back to the client.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamv">LDAPVirtualList</olink></para></entry>
<entry>
<para><olink targetptr="bdamv">LDAPVirtualList</olink> specifies the information
that can be used to create a virtual list view control.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdams">LDAPURLDesc</olink></para></entry>
<entry>
<para><olink targetptr="bdams">LDAPURLDesc</olink> represents the components
of an LDAP URL.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdalg">LDAPFiltInfo</olink></para></entry>
<entry>
<para><olink targetptr="bdalg">LDAPFiltInfo</olink> represents information
about a filter in a filter configuration file.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdalf">LDAPFiltDesc</olink></para></entry>
<entry>
<para><olink targetptr="bdalf">LDAPFiltDesc</olink> is a type of structure
returned when you call <olink targetptr="bdasw">ldap_init_getfilter</olink> to
load a filter configuration file.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaki">FriendlyMap</olink></para></entry>
<entry>
<para><olink targetptr="bdaki">FriendlyMap</olink> represents the mapping
between a list of standard attribute names and their user friendly counterparts.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdalx">LDAPMemCache</olink></para></entry>
<entry>
<para><olink targetptr="bdalx">LDAPMemCache</olink> represents an in-memory,
client-side cache.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink></para></entry>
<entry>
<para><olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink> represents password
policy information concerning an entry.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="ldapuserstatus">LDAPuserstatus</olink></para></entry>
<entry>
<para><olink targetptr="ldapuserstatus">LDAPuserstatus</olink> represents
account availability information.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<note><para>Many other types, especially prototypes for callback functions,
are associated with controls. These are listed separately in the subsequent
sections of this chapter.</para></note>
</sect2>
<sect2 id="bdajz"><title>Referral Binding Callback</title>
<para>This prototype for a callback function retrieves authentication information
when automatically following referrals to other servers.</para>
<table frame="topbot" id="referral-binding"><title>Referral Binding Data Type</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Data Type</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdamb">LDAP_REBINDPROC_CALLBACK</olink></para></entry>
<entry>
<para>Retrieves authentication information when following referrals to other
servers.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdaka"><title>Client-Side Sorting Callbacks</title>
<para>The prototype structures listed in <olink targetptr="client-side-sort-struct">Table 20&ndash;6</olink> are extensions
to &DirectorySDKForC; that implement client side sorting of entries.</para>
<table frame="topbot" id="client-side-sort-struct"><title>Client-side Sorting
Structures</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Data Type</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdalu">LDAP_KEYGEN_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype that generates the sorting key for each entry to
be sorted, usually by extracting a value out of an entry.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdals">LDAP_KEYCMP_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype to compare 2 keys (for ordering).</para></entry>
</row>
<row>
<?PubTbl row rht="0.50in">
<entry>
<para><olink targetptr="bdalt">LDAP_KEYFREE_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype that frees the memory allocated during the <literal>KEYGEN
</literal> callback.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdakz">LDAP_CMP_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype to sort a specified set of entries.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamt">LDAP_VALCMP_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype to sort a specified set of values.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdakb"><title>Extended I/O Control</title>
<para><olink targetptr="extended-io-structs">Table 20&ndash;7</olink> lists
the prototypes and structures used in the extended I/O control, an extension
to the standard API.</para>
<table frame="topbot" id="extended-io-structs"><title>Structures and Prototypes
for Extended I/O Functionality</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Data Type</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdana">ldap_x_ext_io_fns</olink></para></entry>
<entry>
<para>This structure holds extended I/O function pointers.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdand">LDAP_X_PollFD</olink></para></entry>
<entry>
<para>An LDAP file descriptor similar to that of <function>poll</function>.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for a callback that opens a socket connection.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamw">LDAP_X_EXTIOF_CLOSE_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for a callback that closes a socket connection.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdanb">LDAP_X_EXTIOF_POLL_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for a callback that surveys a server about a particular
event.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamz">LDAP_X_EXTIOF_NEWHANDLE_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for a callback that defines a new session handle.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamy">LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for a callback that disposes of a session handle.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdanc">ldap_x_hostlist_status</olink></para></entry>
<entry>
<para>This structure holds utility functions for parsing space-separated host
lists.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdakc"><title>Memory Management Control</title>
<para>The prototypes and structures listed in <olink targetptr="memory-management-structs">Table 20&ndash;8</olink> are used in
memory management control, an extension to the standard API. They allow developers
to specify their own memory allocation mechanisms and functions.</para>
<table frame="topbot" id="memory-management-structs"><title>Memory Management
Data Types</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Data Type</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdalw">ldap_memalloc_fns</olink></para></entry>
<entry>
<para>This structure holds the memory allocation callback functions.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdalv">LDAP_MALLOC_CALLBACK</olink> <olink targetptr="bdakn">LDAP_CALLOC_CALLBACK</olink><olink targetptr="bdama">LDAP_REALLOC_CALLBACK
</olink><olink targetptr="bdalh">LDAP_FREE_CALLBACK</olink></para></entry>
<entry>
<para>These callbacks allow developers to specify their own memory allocation
mechanisms.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdakd"><title>Thread Signaling Controls</title>
<para>The prototypes and structures listed in <olink targetptr="thread-signaling-data-types">Table 20&ndash;9</olink> are used
in the  thread signaling control, an extension to the standard API.</para>
<table frame="topbot" id="thread-signaling-data-types"><title>Thread Signaling
Control Data Types</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Data Type</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdamr">ldap_thread_fns</olink></para></entry>
<entry>
<para>Structure that contains a set of pointers to functions you want to use
when writing a multithreaded client.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamh">LDAP_TF_MUTEX_ALLOC_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for allocating a mutex.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdami">LDAP_TF_MUTEX_FREE_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype freeing a mutex.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamj">LDAP_TF_MUTEX_LOCK_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for locking critical sections of code.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdaml">LDAP_TF_MUTEX_UNLOCK_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for unlocking critical sections of code.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamd">LDAP_TF_GET_ERRNO_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype for getting the value of the <literal>errno</literal> variable.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamf">LDAP_TF_SET_ERRNO_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype for setting the value of the <literal>errno</literal> variable.
</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdame">LDAP_TF_GET_LDERRNO_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for getting error values from calls to functions
in the <literal>libldap</literal> library.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamg">LDAP_TF_SET_LDERRNO_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for setting error values from calls to functions
in the <literal>libldap</literal> library.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdale">ldap_extra_thread_fns</olink></para></entry>
<entry>
<para>Structure that contains a set of pointers to additional functions you
want to use when writing a multithreaded client.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamk">LDAP_TF_MUTEX_TRYLOCK_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for attempting to lock a mutex.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamm">LDAP_TF_SEMA_ALLOC_CALLBACK</olink></para>
</entry>
<entry>
<para>Function prototype for allocating a semaphore.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamn">LDAP_TF_SEMA_FREE_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype for freeing a semaphore.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamp">LDAP_TF_SEMA_WAIT_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype for waiting for the value of a semaphore to be greater
than 0.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamo">LDAP_TF_SEMA_POST_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype for incrementing the value of a semaphore.</para>
</entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamq">LDAP_TF_THREADID_CALLBACK</olink></para></entry>
<entry>
<para>Function prototype to return an identifier that is unique to the calling
thread.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdake"><title>Deprecated and Outdated Types</title>
<para>Deprecated types are those being dropped from the standard or from the
extensions to &DirectorySDKForC;. 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. <olink targetptr="deprecated-structs">Table 20&ndash;10</olink> lists the deprecated
prototypes.</para>
<table frame="topbot" id="deprecated-structs"><title>Deprecated Data Types
and Their Replacements</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Data Type</para></entry>
<entry>
<para>Replacement</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdako">LDAP_CANCELPROC_CALLBACK</olink></para></entry>
<entry>
<para>Provides a way to be  cancel a process, for example, by a user or because
some other condition occurs.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdakm">ldap_cache_fns</olink><olink targetptr="bdakq">LDAP_CF_BIND_CALLBACK
</olink> <olink targetptr="bdaky">LDAP_CF_UNBIND_CALLBACK</olink> <olink targetptr="bdakx">LDAP_CF_SEARCH_CALLBACK</olink><olink targetptr="bdakr">LDAP_CF_COMPARE_CALLBACK
</olink><olink targetptr="bdakp">LDAP_CF_ADD_CALLBACK</olink><olink targetptr="bdaks">LDAP_CF_DELETE_CALLBACK</olink> <olink targetptr="bdaku">LDAP_CF_MODIFY_CALLBACK
</olink> <olink targetptr="bdakv">LDAP_CF_MODRDN_CALLBACK</olink><olink targetptr="bdakw">LDAP_CF_RESULT_CALLBACK</olink><olink targetptr="bdakt">LDAP_CF_FLUSH_CALLBACK
</olink></para></entry>
<entry>
<para><olink targetptr="bdakm">ldap_cache_fns</olink> is a deprecated structure
and the <literal>typedef</literal> declarations associated with it have also
been deprecated.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdamu">LDAPVersion</olink></para></entry>
<entry>
<para>Replaced by the <olink targetptr="bdakl">LDAPAPIInfo</olink> type which
is returned by the <olink targetptr="bdass">ldap_get_option</olink> function
using the  <literal>LDAP_OPT_API_INFO</literal> option.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>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 &DirectorySDKForC;. <olink targetptr="outdated-structs">Table
20&ndash;11</olink> lists the outdated types and the newer types which implement
the same functionality.</para>
<table frame="topbot" id="outdated-structs"><title>Outdated Types and Their
New Equivalents</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Old Data Type</para></entry>
<entry>
<para>New, Equivalent Data Type</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdali">LDAPHostEnt</olink> <?SolBook linebreak><olink targetptr="bdalc">LDAP_DNSFN_GETHOSTBYNAME</olink>  <?SolBook linebreak><olink targetptr="bdalb">LDAP_DNSFN_GETHOSTBYADDR</olink>  <?SolBook linebreak><olink targetptr="bdald">ldap_dns_fns</olink></para></entry>
<entry>
<para>The DNS resolver callbacks are an outdated extension to the API. The
new way of specifying host information is through the <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
</olink>  prototype.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdalj">LDAP_IOF_CLOSE_CALLBACK</olink>  <olink targetptr="bdalk">LDAP_IOF_CONNECT_CALLBACK</olink> <olink targetptr="bdall">LDAP_IOF_IOCTL_CALLBACK
</olink>  <olink targetptr="bdalm">LDAP_IOF_READ_CALLBACK</olink>  <olink targetptr="bdaln">LDAP_IOF_SELECT_CALLBACK</olink> <olink targetptr="bdalo">LDAP_IOF_SOCKET_CALLBACK
</olink>  <olink targetptr="bdalp">LDAP_IOF_SSL_ENABLE_CALLBACK</olink>  <olink targetptr="bdalq">LDAP_IOF_WRITE_CALLBACK</olink> <?SolBook linebreak><olink targetptr="bdalr">ldap_io_fns</olink></para></entry>
<entry>
<para>Replaced by the types for extended I/O functionality detailed in <olink targetptr="extended-io-structs">Table 20&ndash;7</olink>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
</sect1>
<sect1 id="bdakf"><title>Structures Alphabetically</title>
<indexterm>
<primary>C SDK data types</primary>
<secondary>alphabetically</secondary>
</indexterm>
<para>The following sections detail the structures and controls of &DirectorySDKForC;
in alphabetical order.</para>
<sect2 id="bdakg"><title><structname>berval</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>berval</structname></secondary>
</indexterm><indexterm>
<primary><structname>berval</structname></primary>
</indexterm>
<para><literal>berval</literal> is a structure that represents binary data
encoded using simplified Basic Encoding Rules (BER).</para>
<sect3 id="gasmi"><title>Description</title>
<para>Use a <literal>berval</literal> 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 <literal>berval</literal> structure.</para>
<example id="gasmm"><title><structname>berval</structname> Definition</title>
<programlisting>typedef struct berval {
  unsigned long bv_len;
  char *bv_val;
};</programlisting>
</example>
<table frame="topbot" id="gasms"><title><structname>berval</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>bv_len</literal></para></entry>
<entry>
<para>The length of the data in bytes.</para></entry>
</row>
<row>
<entry>
<para><literal>bv_val</literal></para></entry>
<entry>
<para>A pointer to the binary data itself.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdakh"><title><structname>BerElement</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>BerElement</structname></secondary>
</indexterm><indexterm>
<primary><structname>BerElement</structname></primary>
</indexterm>
<para>The <literal>BerElement</literal> structure represents data encoded
using the Basic Encoding Rules (BER).</para>
<sect3 id="gasmg"><title>Description</title>
<para>You use this opaque data type to keep track of the current attribute
during the traversal of an attribute list. Calling the <olink targetptr="bdarw">ldap_first_attribute
</olink>  function allocates memory for a <literal>BerElement</literal> structure
and initializes it to select the values of the first attribute in the entry.
Subsequently, <olink targetptr="bdaua">ldap_next_attribute</olink> is called
to obtain the name of each remaining attribute and set <literal>BerElement</literal> to
select their values. Once <literal>BerElement</literal> has been set to select
an attribute's values, <olink targetptr="bdast">ldap_get_values</olink> can
be used to obtain all of them from the buffer. When you are done reading the
attributes, you need to free the  <literal>BerElement</literal> structure
from memory by calling the  <olink targetptr="bdaqd">ldap_ber_free</olink> function.
(A <literal>BerElement</literal> structure can also be allocated by calling
the <olink targetptr="bdanz">ber_alloc_t</olink> or the <olink targetptr="bdaor">
ber_init</olink> function. In these cases, free the memory allocated to the <literal>
BerElement</literal> structure by using the <olink targetptr="bdaog">ber_free</olink> function.)
</para>
<note><para>The <literal>BerElement</literal> definition is not completely
exposed in <literal>lber.h</literal> because the fields within the structure
are not intended to be accessible to clients.</para></note>
</sect3>
</sect2>
<sect2 id="bdaki"><title><structname>FriendlyMap</structname></title>
<para><literal>FriendlyMap</literal> 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 <literal>FriendlyMap</literal>  structure.</para>
<note><para><literal>FriendlyMap</literal> is not completely defined in  <literal>
ldap-extension.h</literal> because the fields within the structure are not
intended to be accessible to clients.</para></note>
<sect3 id="gasmr"><title>Related Functions</title>
<itemizedlist>
<listitem><para><olink targetptr="bdasj">ldap_friendly_name</olink> allocates
a  <literal>FriendlyMap</literal> structure and reads a list of standard attribute
names and their user friendly counterparts from a file.</para></listitem>
<listitem><para><olink targetptr="bdase">ldap_free_friendlymap</olink> frees
the memory allocated for a <literal>FriendlyMap</literal> structure.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdakj"><title><structname>LDAP</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP</structname> data type</primary>
</indexterm>
<para><literal>LDAP</literal> is an opaque data type representing a connection
with the LDAP server. It is initialized through a call to either the  <olink targetptr="bdasv">ldap_init</olink> or <olink targetptr="bdavs">ldapssl_init</olink> function.
 <literal>LDAP</literal> 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, <olink targetptr="bdauz">ldap_search_ext</olink> to
search the directory or  <olink targetptr="bdatn">ldap_modify_ext</olink> to
update an entry), you need to pass a pointer to this connection handle. With
the <literal>LDAP</literal> structure, you can also:</para>
<itemizedlist>
<listitem><para>Call the <olink targetptr="bdass">ldap_get_option</olink> and <olink targetptr="bdavg">ldap_set_option</olink> functions to view or modify the
properties of the connection.</para></listitem>
<listitem><para>Call the <olink targetptr="bdawh">ldap_unbind</olink> or <olink targetptr="bdawi">ldap_unbind_s</olink> function to close the connection and
free the <literal>LDAP</literal> structure.</para></listitem>
</itemizedlist>
<note><para><literal>LDAP</literal> is not completely defined in <literal>ldap-standard.h
</literal>  because the fields within the structure are not intended to be
accessible to clients.</para></note>
</sect2>
<sect2 id="bdakk"><title><structname>LDAPAPIFeatureInfo</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPAPIFeatureInfo</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPAPIFeatureInfo</structname></primary>
</indexterm>
<para><literal>LDAPAPIFeatureInfo</literal> is a structure that represents
information about the extended features of &DirectorySDKForC;.</para>
<example id="gaslq"><title><structname>LDAPAPIFeatureInfo</structname> Definition
</title>
<programlisting>#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;</programlisting>
</example>
<para>The <literal>LDAPAPIFeatureInfo</literal> structure can be retrieved
by using a sequence like the one displayed in <olink targetptr="get-ldapapifeatureinfo">Example 20&ndash;3</olink>.</para>
<example id="get-ldapapifeatureinfo"><title>Sequence to Retrieve <structname>LDAPAPIFeatureInfo
</structname></title>
<programlisting>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, &amp;ldfi ) == 0 )</programlisting>
</example>
<sect3 id="gasmf"><title>Parameters</title>
<table frame="topbot" id="gasni"><title><structname>LDAPAPIFeatureInfo</structname> Structure
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ldapaif_info_version</literal></para></entry>
<entry>
<para>Specifies the version number of the <literal>LDAPAPIFeatureInfo</literal> structure.
This must be set to <literal>LDAP_FEATURE_INFO_VERSION</literal> before call
to <olink targetptr="bdass">ldap_get_option</olink> is performed.</para></entry>
</row>
<row>
<entry>
<para><literal>ldapaif_name</literal></para></entry>
<entry>
<para>Pointer to <literal>NULL</literal> terminated string that specifies
the name of the supported feature.</para></entry>
</row>
<row>
<entry>
<para><literal>ldapaif_version</literal></para></entry>
<entry>
<para>Specifies the version number of the supported feature.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdakl"><title><structname>LDAPAPIInfo</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPAPIInfo</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPAPIInfo</structname></primary>
</indexterm>
<para><literal>LDAPAPIInfo</literal> is a structure that represents information
about the API and supported extensions.</para>
<example id="gaslo"><title><structname>LDAPAPIInfo</structname> Definition</title>
<programlisting>#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;</programlisting>
</example>
<para>The <literal>LDAPAPIInfo</literal> structure can be retrieved by using
a sequence like the one displayed in <olink targetptr="get-ldapapiinfo">Example
20&ndash;5</olink>.</para>
<example id="get-ldapapiinfo"><title>Sequence to Retrieve <structname>LDAPAPIInfo
</structname></title>
<programlisting>LDAPAPIInfo ldai;
      ldai.ldapai_info_version = LDAP_API_INFO_VERSION;
      if ( ldap_get_option( NULL, LDAP_OPT_API_INFO, &amp;ldia ) == 0 ) ...</programlisting>
</example>
<sect3 id="gaslx"><title>Parameters</title>
<table frame="topbot" id="gaslp"><title><structname>LDAPAPIInfo</structname> Structure
Parameters</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Parameter</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ldapai_info_version</literal></para></entry>
<entry>
<para>Specifies the version number of the <literal>LDAPAPIInfo</literal> structure.
This must be set to <literal>LDAP_API_INFO_VERSION</literal> before a call
to <olink targetptr="bdass">ldap_get_option</olink> is performed.</para></entry>
</row>
<row>
<entry>
<para><literal>ldapai_api_version</literal></para></entry>
<entry>
<para>Specifies the version number of the API that is supported.</para></entry>
</row>
<row>
<entry>
<para><literal>ldapai_protocol_version</literal></para></entry>
<entry>
<para>Specifies the latest LDAP version supported by the LDAP library.</para>
</entry>
</row>
<row>
<entry>
<para><literal>ldapai_extensions</literal></para></entry>
<entry>
<para>Points to a <literal>NULL</literal> terminated array of character strings
that names the supported LDAP extensions. If none are supported, this field
is set to  <literal>NULL</literal>. The application is responsible for freeing
this memory by calling the <olink targetptr="bdaxc">ldap_value_free</olink> function.
</para></entry>
</row>
<row>
<entry>
<para><literal>ldapai_vendor_name</literal></para></entry>
<entry>
<para>Pointer to a NULL-terminated string that contains the vendor's name.
Call the <olink targetptr="bdatl">ldap_memfree</olink> function to free the
memory.</para></entry>
</row>
<row>
<entry>
<para><literal>ldapai_vendor_version</literal></para></entry>
<entry>
<para>Specifies the vendor&rsquo;s version of the LDAP libraries.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdakm"><title><structname>ldap_cache_fns</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>ldap_cache_fns</structname></secondary>
</indexterm><indexterm>
<primary><structname>ldap_cache_fns</structname></primary>
</indexterm>
<para><literal>ldap_cache_fns</literal> is a deprecated structure. The following
are also deprecated:</para>
<itemizedlist>
<listitem><para><olink targetptr="bdakp">LDAP_CF_ADD_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdakq">LDAP_CF_BIND_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdakr">LDAP_CF_COMPARE_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdaks">LDAP_CF_DELETE_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdakt">LDAP_CF_FLUSH_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdaku">LDAP_CF_MODIFY_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdakv">LDAP_CF_MODRDN_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdakw">LDAP_CF_RESULT_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdakx">LDAP_CF_SEARCH_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdaky">LDAP_CF_UNBIND_CALLBACK</olink></para>
</listitem>
</itemizedlist>
<sect3 id="gasmv"><title>See Also</title>
<para>Please see the <literal>ldap_memcache_*</literal> functions for current
usage.</para></sect3>
</sect2>
<sect2 id="bdakn"><title><structname>LDAP_CALLOC_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CALLOC_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CALLOC_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdalw">ldap_memalloc_fns
</olink>  represents memory allocation.</para>
<sect3 id="gasng"><title>See Also</title>
<para><olink targetptr="bdalw">ldap_memalloc_fns</olink></para></sect3>
</sect2>
<sect2 id="bdako"><title><structname>LDAP_CANCELPROC_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CANCELPROC_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CANCELPROC_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype is deprecated.</para>
<sect3 id="gasmt"><title>See Also</title>
<para><olink targetptr="bdawb">ldap_ufn_search_c</olink>,  <olink targetptr="bdawc">ldap_ufn_search_ct</olink></para></sect3>
</sect2>
<sect2 id="bdakp"><title><structname>LDAP_CF_ADD_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_ADD_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_ADD_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdakq"><title><structname>LDAP_CF_BIND_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_BIND_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_BIND_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdakr"><title><structname>LDAP_CF_COMPARE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_COMPARE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_COMPARE_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdaks"><title><structname>LDAP_CF_DELETE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_DELETE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_DELETE_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdakt"><title><structname>LDAP_CF_FLUSH_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_FLUSH_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_FLUSH_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdaku"><title><structname>LDAP_CF_MODIFY_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_MODIFY_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_MODIFY_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdakv"><title><structname>LDAP_CF_MODRDN_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_MODRDN_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_MODRDN_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdakw"><title><structname>LDAP_CF_RESULT_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_RESULT_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_RESULT_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdakx"><title><structname>LDAP_CF_SEARCH_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_SEARCH_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_SEARCH_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdaky"><title><structname>LDAP_CF_UNBIND_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CF_UNBIND_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CF_UNBIND_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdakm">ldap_cache_fns
</olink>  is deprecated.</para></sect2>
<sect2 id="bdakz"><title><structname>LDAP_CMP_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_CMP_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_CMP_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_CMP_CALLBACK</literal> 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 <olink targetptr="bdavk">ldap_sort_entries
</olink> or <olink targetptr="bdaty">ldap_multisort_entries</olink>, it will
be called by your LDAP client to sort a specified set of entries.</para>
<example id="gaslr"><title><structname>LDAP_CMP_CALLBACK</structname> Prototype</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_CMP_CALLBACK)(const char*, const char*);</programlisting>
</example>
<sect3 id="gasnc"><title>See Also</title>
<para><olink targetptr="bdavk">ldap_sort_entries</olink>,  <olink targetptr="bdaty">ldap_multisort_entries</olink>.</para></sect3>
</sect2>
<sect2 id="bdala"><title><structname>LDAPControl</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPControl</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPControl</structname></primary>
</indexterm>
<para><literal>LDAPControl</literal> 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.</para>
<para>Controls are part of the LDAP v3. You can use a control to extend the
functionality of an LDAP operation. There are two basic types of controls
described in the LDAP v3:</para>
<itemizedlist>
<listitem><para><emphasis>Server controls</emphasis> 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.</para>
</listitem>
<listitem><para><emphasis>Client controls</emphasis> 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&rsquo;ve specified in the
control.</para><para>&DirectorySDKForC; does not currently support any
client controls.</para></listitem>
</itemizedlist>
<example id="gasmq"><title>Definition of <structname>LDAPControl</structname></title>
<programlisting>typedef struct ldapcontrol {
  char *ldctl_oid;
  struct berval ldctl_value;
  char ldctl_iscritical;
} LDAPControl;</programlisting>
</example>
<table frame="topbot" id="gasmp"><title><structname>LDAPControl</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ldctl_oid</literal></para></entry>
<entry>
<para>Object identifier (OID) of the control.</para></entry>
</row>
<row>
<entry>
<para><literal>ldctl_value</literal></para></entry>
<entry>
<para><olink targetptr="bdakg">berval</olink> structure containing data associated
with the control. If you want to specify a zero-length value, set <literal>ldctl_value.bv_len
</literal>  to <literal>0</literal> and <literal>ldctl_value.bv_val</literal> to
a zero-length string. To indicate that no data is associated with the control,
set  <literal>ldctl_value.bv_val</literal> to <literal>NULL</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><literal>ldctl_iscritical</literal></para></entry>
<entry>
<para>Specifies whether or not the control is critical to the operation. This
field can have one of the following values:</para>
<itemizedlist>
<listitem><para>A non-zero value specifies that the control is critical to
the operation.</para></listitem>
<listitem><para><literal>0</literal> specifies that the control is not critical
to the operation.</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdalb"><title><structname>LDAP_DNSFN_GETHOSTBYADDR</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_DNSFN_GETHOSTBYADDR</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_DNSFN_GETHOSTBYADDR</structname></primary>
</indexterm>
<para><literal>LDAP_DNSFN_GETHOSTBYADDR</literal> specifies the prototype
for a callback function equivalent to the <literal>gethostbyaddr_r()</literal> function
available on some <trademark class="registered">UNIX</trademark> platforms.</para>
<note><para>While not officially deprecated, the functionality of this callback
prototype is superseded by the extended I/O functions. The new way of specifying
host information is through the <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
</olink>  prototype.</para></note>
<sect3 id="gaslu"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdald">ldap_dns_fns</olink> 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.</para>
<note><para>In this version of &DirectorySDKForC;, the functions of the
API never call this function, and your implementation will never be executed.
Therefore, its implementation is optional.</para></note>
<example id="gasnh"><title><structname>LDAP_DNSFN_GETHOSTBYADDR</structname> Prototype
</title>
<programlisting>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 );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdalc"><title><structname>LDAP_DNSFN_GETHOSTBYNAME</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_DNSFN_GETHOSTBYNAME</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_DNSFN_GETHOSTBYNAME</structname></primary>
</indexterm>
<para><literal>LDAP_DNSFN_GETHOSTBYNAME</literal> specifies the prototype
for a callback function equivalent to the <literal>gethostbyname_r()</literal> function
available on some UNIX platforms.</para>
<note><para>While not officially deprecated, the functionality of this callback
prototype is superseded by the extended I/O functions. The new way of specifying
host information is through the <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
</olink>  prototype.</para></note>
<sect3 id="gaslt"><title>Description</title>
<para>If you define a function with this prototype and set it in the <literal>ldap_dns_fns
</literal>  structure, your function will be called by &DirectorySDKForC;
on behalf of your LDAP client to get the host entry for the LDAP server when
connecting to the server.</para>
<example id="gasmc"><title><structname>LDAP_DNSFN_GETHOSTBYNAME</structname> Prototype
</title>
<programlisting>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 );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdald"><title><structname>ldap_dns_fns</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>ldap_dns_fns</structname></secondary>
</indexterm><indexterm>
<primary><structname>ldap_dns_fns</structname></primary>
</indexterm>
<para><literal>ldap_dns_fns</literal> contains a set of pointers to DNS functions
and is equivalent to the <literal>gethostbyname_r()</literal> and <literal>gethostbyaddr_r()
</literal>  functions available on some UNIX platforms.</para>
<note><para>While not officially deprecated, the functionality of this structure
is superseded by the extended I/O functions. The new way of specifying host
information is through the <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
</olink> prototype.</para></note>
<sect3 id="gasmn"><title>Description</title>
<para>You can use this structure if you want &DirectorySDKForC; 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 multithreaded application. The function must have the
prototype specified by  <olink targetptr="bdalb">LDAP_DNSFN_GETHOSTBYADDR</olink>.
If <literal>NULL</literal>, the standard built-in OS routine is used.</para>
<para>After you set the fields in this structure, you can register the functions
for use by calling the <olink targetptr="bdavg">ldap_set_option</olink> function
and setting the <literal>LDAP_OPT_DNS_FN_PTRS</literal> option to this structure.
</para>
<example id="gasna"><title><structname>ldap_dns_fns</structname> Definition</title>
<programlisting>struct ldap_dns_fns {
  void *lddnsfn_extradata;
  int lddnsfn_bufsize;
  LDAP_DNSFN_GETHOSTBYNAME *lddnsfn_gethostbyname;
  LDAP_DNSFN_GETHOSTBYADDR *lddnsfn_gethostbyaddr;
};</programlisting>
</example>
<table frame="topbot" id="gasme"><title><structname>ldap_dns_fns</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lddnsfn_extradata</literal></para></entry>
<entry>
<para>Value passed in the <literal>extradata</literal> argument of the  <olink targetptr="bdalb">LDAP_DNSFN_GETHOSTBYADDR</olink> and <olink targetptr="bdalc">LDAP_DNSFN_GETHOSTBYNAME
</olink>  function calls.</para></entry>
</row>
<row>
<entry>
<para><literal>lddnsfn_bufsize</literal></para></entry>
<entry>
<para>Specifies the size of the buffer that you want passed to your DNS callback
function. Your LDAP client passes this value as the <literal>buflen</literal> argument
of the <olink targetptr="bdalb">LDAP_DNSFN_GETHOSTBYADDR</olink> and <olink targetptr="bdalc">LDAP_DNSFN_GETHOSTBYNAME</olink>  function calls.</para>
</entry>
</row>
<row>
<entry>
<para><literal>lddnsfn_gethostbyname</literal></para></entry>
<entry>
<para>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  <literal>NULL</literal>. The function must have the prototype
specified by  <olink targetptr="bdalc">LDAP_DNSFN_GETHOSTBYNAME</olink>. If <literal>
NULL</literal>, the standard built-in OS routine is used.</para></entry>
</row>
<row>
<entry>
<para><literal>lddnsfn_gethostbyaddr</literal></para></entry>
<entry>
<para>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 <literal>
NULL</literal>.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdale"><title><structname>ldap_extra_thread_fns</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>ldap_extra_thread_fns</structname></secondary>
</indexterm><indexterm>
<primary><structname>ldap_extra_thread_fns</structname></primary>
</indexterm>
<para>The <literal>ldap_extra_thread_fns</literal> 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  <olink targetptr="bdakj">LDAP</olink> structure.</para>
<note><para>&DirectorySDKForC; ignores all the elements in this structure
except for the <literal>ltf_threadid_fn</literal> function. Calling <literal>ltf_threadid_fn
</literal>  will, in some cases, enhance the performance of a multithreaded
program.</para></note>
<para>After you set the fields in this structure, you can register the functions
for use by calling the <olink targetptr="bdavg">ldap_set_option</olink> function
and setting the <literal>LDAP_OPT_EXTRA_THREAD_FN_PTRS</literal> option to
this structure.</para>
<example id="gaslw"><title><structname>ldap_extra_thread_fns</structname> Definition
</title>
<programlisting>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;
};</programlisting>
</example>
<table frame="topbot" id="gasls"><title><structname>ldap_extra_thread_fns</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ltf_mutex_trylock</literal></para></entry>
<entry>
<para>Function pointer for attempting to lock a mutex. This function is called
by the client when needed if the function pointer is not <literal>NULL</literal>.
The function must have the prototype specified by <olink targetptr="bdamk">LDAP_TF_MUTEX_TRYLOCK_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_sema_alloc</literal></para></entry>
<entry>
<para>Function pointer for allocating a semaphore. This finction is called
by the client if needed when the function pointer is not <literal>NULL</literal>.
The function must have the prototype specified by <olink targetptr="bdamm">LDAP_TF_SEMA_ALLOC_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_sema_free</literal></para></entry>
<entry>
<para>Function pointer for freeing a semaphore. This function is called by
the client when needed if the function pointer is not <literal>NULL</literal>.
The function must have the prototype specified by <olink targetptr="bdamn">LDAP_TF_SEMA_FREE_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_sema_wait</literal></para></entry>
<entry>
<para>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  <literal>NULL</literal>. The function must have the prototype
specified by  <olink targetptr="bdamp">LDAP_TF_SEMA_WAIT_CALLBACK</olink>.</para>
</entry>
</row>
<row>
<entry>
<para><literal>ltf_sema_post</literal></para></entry>
<entry>
<para>Function pointer for incrementing the value of a semaphore. This function
is called by the client when needed if the function pointer is not <literal>NULL</literal>.
The function must have the prototype specified by <olink targetptr="bdamo">LDAP_TF_SEMA_POST_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_threadid_fn</literal></para></entry>
<entry>
<para>Function pointer that is called to retrieve the unique identifier for
the calling thread. If this is <literal>NULL</literal>, it is not used. An
example of a similar function in the POSIX threads standard is <literal>pthread_self()
</literal>. The function must have the prototype specified by <olink targetptr="bdamq">LDAP_TF_THREADID_CALLBACK</olink> .</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdalf"><title><structname>LDAPFiltDesc</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPFiltDesc</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPFiltDesc</structname></primary>
</indexterm>
<para><literal>LDAPFiltDesc</literal> is a structure that is returned when
you call <olink targetptr="bdasw">ldap_init_getfilter</olink> to load a filter
configuration file.</para>
<note><para>The <literal>LDAPFiltDesc</literal> definition is not completely
exposed in <literal>ldap-extension.h</literal> because the fields within the
structure are not intended to be accessible to clients.</para></note>
<sect3 id="gasmx"><title>Description</title>
<para>After calling the <olink targetptr="bdasw">ldap_init_getfilter</olink> function,
use the pointer to the returned <literal>LDAPFiltDesc</literal> structure
in subsequent calls to get information about filters in the filter configuration
file.</para></sect3>
</sect2>
<sect2 id="bdalg"><title><structname>LDAPFiltInfo</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPFiltInfo</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPFiltInfo</structname></primary>
</indexterm>
<para><literal>LDAPFiltInfo</literal> represents information about a filter
in the filter configuration file.</para>
<sect3 id="gasmj"><title>Description</title>
<para>When you call the <olink targetptr="bdasn">ldap_getfirstfilter</olink> or <olink targetptr="bdasr">ldap_getnextfilter</olink> functions to get a filter from
the filter configuration file, they return a pointer to an <literal>LDAPFiltInfo</literal> structure
containing the information about the filter.</para>
<example id="gasml"><title><structname>LDAPFiltInfo</structname> Definition</title>
<programlisting>typedef struct ldap_filt_info {
  char *lfi_filter;
  char *lfi_desc;
  int lfi_scope;
  int lfi_isexact;
  struct ldap_filt_info *lfi_next;
} LDAPFiltInfo;</programlisting>
</example>
<table frame="topbot" id="gasmz"><title><structname>LDAPFilterInfo</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lfi_filter</literal></para></entry>
<entry>
<para>The filter, for example <literal>(cn=d*)</literal>.</para></entry>
</row>
<row>
<entry>
<para><literal>lfi_desc</literal></para></entry>
<entry>
<para>Description of the filter, also the fifth field in the filter configuration
file.</para></entry>
</row>
<row>
<entry>
<para><literal>lfi_scope</literal></para></entry>
<entry>
<para>The scope of the filter, also the sixth field in the filter configuration
file, which can be one of the following values:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SCOPE_BASE</literal> specifies that the search
will be restricted to the current DN.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> specifies that the
search will be restricted to the entries at the level beneath the current
DN.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> specifies that the search
will encompass entries at all levels beneath the current DN.</para><para>If
the scope of the filter is not specified in the filter configuration file,
the scope is  <literal>LDAP_SCOPE_SUBTREE</literal> by default.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>lfi_isexact</literal></para></entry>
<entry>
<para>Specifies whether or not the filter is an exact filter, where an exact
filter contains no wildcard characters and does not match words that sound
alike:</para>
<itemizedlist>
<listitem><para><literal>0</literal> specifies that the filter is not an exact
filter.</para></listitem>
<listitem><para><literal>1</literal> specifies that the filter is an exact
filter.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>lfi_next</literal></para></entry>
<entry>
<para>Pointer to the <literal>LDAPFiltInfo</literal> structure representing
the next filter in the filter list.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para><olink targetptr="get-ldapfiltinfo">Example 20&ndash;13</olink> prints
out information about a filter.</para>
<example id="get-ldapfiltinfo"><title>Sample <structname>LDAPFiltInfo</structname> Code
</title>
<programlisting>LDAPFiltInfo *lfip;
/* Print out the filter */
printf( "Filter:\t%s\n", lfdp->lfd_filter );
printf( "Description:\t%s\n", lfdp->lfd_desc );</programlisting>
</example>
<para>For example, in the filter configuration file, if the first filter that
applies to the value <literal>@</literal> is:</para>
<programlisting>"@" " " "(mail=%v)" "email address is" "onelevel"</programlisting>
<para>The code prints out:</para>
<programlisting>Filter: (mail=@)
Description: email address is</programlisting>
</sect3>
</sect2>
<sect2 id="bdalh"><title><structname>LDAP_FREE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_FREE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_FREE_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdalw">ldap_memalloc_fns
</olink>  is used to free allocated memory.</para>
<sect3 id="gasne"><title>See Also</title>
<para><olink targetptr="bdalw">ldap_memalloc_fns</olink></para></sect3>
</sect2>
<sect2 id="bdali"><title><structname>LDAPHostEnt</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPHostEnt</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPHostEnt</structname></primary>
</indexterm>
<para>The <literal>LDAPHostEnt</literal> structure represents an entry for
a host found by a domain name server.</para>
<note><para>While not officially deprecated, the functionality of this callback
prototype is superseded by the extended I/O functions. The new way of specifying
host information is through the <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
</olink>  prototype.</para></note>
<sect3 id="gasmw"><title>Description</title>
<para>This type is similar to the <literal>hostent</literal> structure returned
by functions such as <literal>gethostbyname_r()</literal> on UNIX systems.
If you are writing your own DNS functions for use by the client, they should
return the host entry in this type of structure.</para>
<para>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.</para>
<example id="gasnd"><title><structname>LDAPHostEnt</structname> Definition</title>
<programlisting>typedef struct LDAPHostEnt {
  char *ldaphe_name;
  char **ldaphe_aliases;
  int ldaphe_addrtype;
  int ldaphe_length;
  char **ldaphe_addr_list;
} LDAPHostEnt;</programlisting>
</example>
<table frame="topbot" id="gasnj"><title><structname>LDAPHostEnt</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ldaphe_name</literal></para></entry>
<entry>
<para>Canonical name of the host</para></entry>
</row>
<row>
<entry>
<para><literal>ldaphe_aliases</literal></para></entry>
<entry>
<para>List of aliases for this host</para></entry>
</row>
<row>
<entry>
<para><literal>ldaphe_addrtype</literal></para></entry>
<entry>
<para>Address type of the host</para></entry>
</row>
<row>
<entry>
<para><literal>ldaphe_length</literal></para></entry>
<entry>
<para>Length of the address</para></entry>
</row>
<row>
<entry>
<para><literal>ldaphe_addr_list</literal></para></entry>
<entry>
<para>List of addresses for this host as returned by the name server</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="gasmu"><title>See Also</title>
<para><olink targetptr="bdalb">LDAP_DNSFN_GETHOSTBYADDR</olink>,  <olink targetptr="bdalc">LDAP_DNSFN_GETHOSTBYNAME</olink></para></sect3>
</sect2>
<sect2 id="bdalj"><title><structname>LDAP_IOF_CLOSE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_IOF_CLOSE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_IOF_CLOSE_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_IOF_CLOSE_CONNECT_CALLBACK</literal> specifies the prototype
for a callback function equivalent to the standard <function>close</function> system
call.</para>
<sect3 id="gasnb"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdalr">ldap_io_fns</olink> structure, the function will be called
by your LDAP client.</para>
<example id="gasnk"><title><structname>LDAP_IOF_CLOSE_CONNECT_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_CLOSE_CALLBACK )( LBER_SOCKET );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdalk"><title><structname>LDAP_IOF_CONNECT_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_IOF_CONNECT_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_IOF_CONNECT_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_IOF_CONNECT_CALLBACK</literal> specifies the prototype
for a callback function equivalent to the standard <function>connect</function> network
I/O function.</para>
<sect3 id="gasly"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdalr">ldap_io_fns</olink> structure, the function will be called
by your LDAP client.</para>
<example id="gasmd"><title><structname>LDAP_IOF_CONNECT_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_CONNECT_CALLBACK )( LBER_SOCKET,
  struct sockaddr *, int );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdall"><title><structname>LDAP_IOF_IOCTL_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_IOF_IOCTL_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_IOF_IOCTL_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_IOF_IOCTL_CALLBACK</literal> specifies the prototype for
a callback function equivalent to the standard <function>ioctl</function> system
call.</para>
<sect3 id="gaslz"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdalr">ldap_io_fns</olink> structure, the function will be called
by your LDAP client.</para>
<example id="gasma"><title><structname>LDAP_IOF_IOCTL_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_IOCTL_CALLBACK)( LBER_SOCKET, int, ... );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdalm"><title><structname>LDAP_IOF_READ_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_IOF_READ_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_IOF_READ_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_IOF_READ_CALLBACK</literal> specifies the prototype for
a callback function equivalent to the standard <function>read</function> I/O
function.</para>
<sect3 id="gasln"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdalr">ldap_io_fns</olink> structure, the function will be called
by your LDAP client.</para>
<example id="gasmh"><title><structname>LDAP_IOF_READ_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_READ_CALLBACK)( LBER_SOCKET, void *, int );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdaln"><title><structname>LDAP_IOF_SELECT_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_IOF_SELECT_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_IOF_SELECT_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_IOF_SELECT_CALLBACK</literal> specifies the prototype
for a callback function equivalent to the standard <function>select</function> I/O
function.</para>
<sect3 id="gasmy"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdalr">ldap_io_fns</olink> structure, the function will be called
by your LDAP client.</para>
<example id="gasmb"><title><structname>LDAP_IOF_SELECT_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
LDAP_IOF_SELECT_CALLBACK)( int, fd_set *, fd_set *,
  fd_set *, struct timeval * );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdalo"><title><structname>LDAP_IOF_SOCKET_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_IOF_SOCKET_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_IOF_SOCKET_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_IOF_SOCKET_CALLBACK</literal> specifies the prototype
for a callback function equivalent to the standard <function>socket</function> network
I/O function.</para>
<sect3 id="gasmk"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdalr">ldap_io_fns</olink> structure, the function will be called
by your LDAP client.</para>
<example id="gaslv"><title><structname>LDAP_IOF_SOCKET_CALLBACK</structname> Prototype
</title>
<programlisting>typedef LBER_SOCKET (LDAP_C LDAP_CALLBACK
  LDAP_IOF_SOCKET_CALLBACK)( int, int, int );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdalp"><title><structname>LDAP_IOF_SSL_ENABLE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_IOF_SSL_ENABLE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_IOF_SSL_ENABLE_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_IOF_SSL_ENABLE_CALLBACK</literal> specifies the prototype
for a callback function equivalent to the <function>ssl_enable</function> function.
</para>
<sect3 id="gasmo"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdalr">ldap_io_fns</olink> structure, the function will be called
by your LDAP client.</para>
<example id="gasnl"><title><structname>LDAP_IOF_SSL_ENABLE_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_IOF_SSL_ENABLE_CALLBACK )( LBER_SOCKET );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdalq"><title><structname>LDAP_IOF_WRITE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_IOF_WRITE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_IOF_WRITE_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_IOF_WRITE_CALLBACK</literal> specifies the prototype for
a callback function equivalent to the standard <function>write</function> I/O
function.</para>
<sect3 id="gasnp"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdalr">ldap_io_fns</olink> structure, the function will be called
by your LDAP client.</para>
<example id="gasoa"><title><structname>LDAP_IOF_WRITE_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK LDAP_IOF_WRITE_CALLBACK)
  ( LBER_SOCKET, const void *, int );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdalr"><title><structname>ldap_io_fns</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>ldap_io_fns</structname></secondary>
</indexterm><indexterm>
<primary><structname>ldap_io_fns</structname></primary>
</indexterm>
<para>The <literal>ldap_io_fns</literal> 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).</para>
<example id="gasod"><title><structname>ldap_io_fns</structname> Structure</title>
<programlisting>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;
};</programlisting>
</example>
<table frame="topbot" id="ldap-io-fns-fields"><title><structname>ldap_io_fns</structname> Field
Descriptions</title>
<tgroup cols="2"><?Pub Dtl><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>liof_read</literal></para></entry>
<entry>
<para>Function pointer to the equivalent of the standard <literal>read()</literal> I/O
function. The function must have the prototype specified by  <olink targetptr="bdalm">LDAP_IOF_READ_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>liof_write</literal></para></entry>
<entry>
<para>Function pointer to the equivalent of the standard <literal>write()</literal> I/O
function. The function must have the prototype specified by  <olink targetptr="bdalq">LDAP_IOF_WRITE_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>liof_select</literal></para></entry>
<entry>
<para>Function pointer to the equivalent of the standard <literal>select()</literal> I/O
function. The function must have the prototype specified by  <olink targetptr="bdaln">LDAP_IOF_SELECT_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>liof_socket</literal></para></entry>
<entry>
<para>Function pointer to the equivalent of the standard <literal>socket()</literal> network
I/O function. The function must have the prototype specified by  <olink targetptr="bdalo">LDAP_IOF_SOCKET_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>liof_ioctl</literal></para></entry>
<entry>
<para>Function pointer to the equivalent of the standard <literal>ioctl()</literal> system
call. The function must have the prototype specified by  <olink targetptr="bdall">
LDAP_IOF_IOCTL_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>liof_connect</literal></para></entry>
<entry>
<para>Function pointer to the equivalent of the standard <literal>connect()</literal> network
I/O function. The function must have the prototype specified by  <olink targetptr="bdalk">LDAP_IOF_CONNECT_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>liof_close</literal></para></entry>
<entry>
<para>Function pointer to the equivalent of the standard <literal>close()</literal> system
call. The function must have the prototype specified by  <olink targetptr="bdalj">
LDAP_IOF_CLOSE_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>liof_ssl_enable</literal></para></entry>
<entry>
<para>Function pointer to the equivalent of the <literal>ssl_enable()</literal> function.
The function must have the prototype specified by <olink targetptr="bdalp">LDAP_IOF_SSL_ENABLE_CALLBACK
</olink> .</para></entry>
</row>
</tbody>
</tgroup>
</table>
<sect3 id="bdals"><title><structname>LDAP_KEYCMP_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_KEYCMP_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_KEYCMP__CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_KEYCMP_CALLBACK</literal> specifies the prototype for
a callback function to sort a specified set of entries.</para></sect3>
<sect3 id="gaspi"><title>Definition</title>
<para>If you define a function with this prototype and specify it when calling <olink targetptr="bdate">ldap_keysort_entries</olink>, the function will be called
by your LDAP client to sort a specified set of entries.</para></sect3>
<sect3 id="gasoo"><title>See Also</title>
<para><olink targetptr="bdate">ldap_keysort_entries</olink></para></sect3>
</sect2>
<sect2 id="bdalt"><title><structname>LDAP_KEYFREE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_KEYFREE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_KEYFREE__CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_KEYFREE_CALLBACK</literal> specifies the prototype for
a callback function that frees a sorting key.</para>
<sect3 id="gaspa"><title>Description</title>
<para><olink targetptr="bdate">ldap_keysort_entries</olink> requires a function
pointer that matches the signature defined by this type.</para></sect3>
</sect2>
<sect2 id="bdalu"><title><structname>LDAP_KEYGEN_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_KEYGEN_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_KEYGEN__CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_KEYGEN_CALLBACK</literal> specifies the prototype for
a callback function that generates a key for sorting.</para>
<sect3 id="gasot"><title>Description</title>
<para><olink targetptr="bdate">ldap_keysort_entries</olink> requires a function
pointer that matches the signature defined by this type.</para></sect3>
</sect2>
<sect2 id="bdalv"><title><structname>LDAP_MALLOC_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_MALLOC_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_MALLOC__CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdalw">ldap_memalloc_fns
</olink>  represents memory allocation.</para>
<sect3 id="gasok"><title>See Also</title>
<para><olink targetptr="bdalw">ldap_memalloc_fns</olink></para></sect3>
</sect2>
<sect2 id="bdalw"><title><structname>ldap_memalloc_fns</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>ldap_memalloc_fns</structname></secondary>
</indexterm><indexterm>
<primary><structname>ldap_memalloc_fns</structname></primary>
</indexterm>
<para><literal>ldap_memalloc_fns</literal> 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 <olink targetptr="installing-ldap-memalloc-fns">Example
20&ndash;24</olink>.</para>
<example id="installing-ldap-memalloc-fns"><title>Installing <structname>ldap_memalloc_fns
</structname></title>
<programlisting>ldap_set_option(NULL, LDAP_OPT_MEMALLOC_FN_PTRS, &amp;memalloc_fns);
</programlisting>
</example>
<sect3 id="gasoh"><title>See Also</title>
<itemizedlist>
<listitem><para><olink targetptr="bdalv">LDAP_MALLOC_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdakn">LDAP_CALLOC_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdama">LDAP_REALLOC_CALLBACK</olink></para>
</listitem>
<listitem><para><olink targetptr="bdalh">LDAP_FREE_CALLBACK</olink></para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdalx"><title><structname>LDAPMemCache</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPMemCache</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPMemCache</structname></primary>
</indexterm>
<para><literal>LDAPMemCache</literal> is a type of structure representing
an in-memory, client-side cache. You can create a cache and specify the following
information:</para>
<itemizedlist>
<listitem><para>The maximum size of the cache.</para></listitem>
<listitem><para>The maximum amount of time to keep an item in the cache.</para>
</listitem>
<listitem><para>A set of base DNs for the search requests that you want to
cache (optional).</para></listitem>
<listitem><para>A set of functions to ensure the thread-safety of the cache.</para>
<para>To use a cache, you need to associate it with a connection handle (and <olink targetptr="bdakj">LDAP</olink> 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.</para></listitem>
</itemizedlist>
<note><para>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  <literal>uid</literal> 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 <literal>uid</literal>, the
result cached from the previous search are not used.</para></note>
<para>The cache uses a combination of the following information as the key
to a cached item:</para>
<itemizedlist>
<listitem><para>The host name and port number of the LDAP server that you
are searching.</para></listitem>
<listitem><para>The DN to which you are currently authenticated.</para><para>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.</para></listitem>
</itemizedlist>
<sect3 id="gasnr"><title>Related Functions</title>
<para><olink targetptr="ldapmemcache-functions">Table 20&ndash;21</olink> lists
functions related to the  <literal>LDAPMemCache</literal> structure.</para>
<table frame="topbot" id="ldapmemcache-functions"><title>Functions for <structname>
LDAPMemCache</structname> Structure</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Function</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><olink targetptr="bdati">ldap_memcache_init</olink></para></entry>
<entry>
<para>Creates an <literal>LDAPMemCache</literal> structure and initialize
the caching mechanism.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatj">ldap_memcache_set</olink></para></entry>
<entry>
<para>Associates an <literal>LDAPMemCache</literal> structure with a connection
handle (an LDAP structure).</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdath">ldap_memcache_get</olink></para></entry>
<entry>
<para>Returns the <literal>LDAPMemCache</literal> structure that is associated
with a connection handle (an LDAP structure).</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatk">ldap_memcache_update</olink></para></entry>
<entry>
<para>Forces the cache to remove expired items.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatg">ldap_memcache_flush</olink></para></entry>
<entry>
<para>Removes entries from the cache.</para></entry>
</row>
<row>
<entry>
<para><olink targetptr="bdatf">ldap_memcache_destroy</olink></para></entry>
<entry>
<para>Frees the memory used by the cache and frees the <literal>LDAPMemCache</literal> structure.
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="bdaly"><title><structname>LDAPMessage</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPMessage</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPMessage</structname></primary>
</indexterm>
<para><literal>LDAPMessage</literal> is a structure representing the results
of an LDAP operation such as a chain of search results, an entry in the search
results, or a search reference in the search results.</para>
<note><para><literal>LDAPMessage</literal> is not completely defined in  <literal>
ldap.h</literal> because the fields within the structure are not intended
to be directly accessible to clients.</para></note>
</sect3>
<sect3 id="gasoj"><title>Description</title>
<para>Calling the <olink targetptr="bdava">ldap_search_ext_s</olink> or  <olink targetptr="bdauz">ldap_search_ext</olink> followed by the <olink targetptr="bdauu">ldap_result</olink> function creates an <literal>LDAPMessage</literal> structure
to represent the chain of results from the search. Calling the <olink targetptr="bdary">ldap_first_entry</olink> or <olink targetptr="bdauc">ldap_next_entry
</olink> function creates an <literal>LDAPMessage</literal>  structure to
represent an entry in the search results. Calling  <olink targetptr="bdasa">ldap_first_reference
</olink> or <olink targetptr="bdaue">ldap_next_reference</olink> creates an <literal>
LDAPMessage</literal> structure to represent a search reference in the search
results. To free the <literal>LDAPMessage</literal> structure, call the <olink targetptr="bdatv">ldap_msgfree</olink> routine.</para></sect3>
</sect2>
<sect2 id="bdalz"><title><structname>LDAPMod</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPMod</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPMod</structname></primary>
</indexterm>
<para><literal>LDAPMod</literal> is a structure that you use to specify changes
to an attribute in a directory entry.</para>
<sect3 id="gasns"><title>Description</title>
<para>Before you call the <olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdaqb">ldap_add_ext_s</olink>, <olink targetptr="bdatn">ldap_modify_ext
</olink> , or <olink targetptr="bdato">ldap_modify_ext_s</olink> functions
to add or modify an entry in the directory, you need to fill <literal>LDAPMod</literal> structures
with the attribute values that you intend to add or change.</para>
<example id="gaspb"><title><structname>LDAPMod</structname> Definition</title>
<programlisting>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;</programlisting>
</example>
<table frame="topbot" id="gaspf"><title><structname>LDAPMod</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>mod_op</literal></para></entry>
<entry>
<para>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:</para>
<itemizedlist>
<listitem><para><literal>LDAP_MOD_ADD</literal> adds a value to the attribute.</para>
</listitem>
<listitem><para><literal>LDAP_MOD_DELETE</literal> removes the value from
the attribute.</para></listitem>
<listitem><para><literal>LDAP_MOD_REPLACE</literal> replaces all existing
values of the attribute.</para><para>In addition, if you are specifying binary
values in the  <literal>mod_bvalues</literal> field, you should use the bitwise <literal>
OR</literal> operator ( <literal>|</literal> ) to combine <literal>LDAP_MOD_BVALUES
</literal> with the operation type. For example:</para><para><literal>mod->mod_op
= LDAP_MOD_ADD | LDAP_MOD_BVALUES</literal></para><para>Note the following
caveats when defining :</para></listitem>
<listitem><para>If you specify <literal>LDAP_MOD_DELETE</literal> and remove
all values in an attribute, the attribute is removed from the entry.</para>
</listitem>
<listitem><para>If you specify <literal>LDAP_MOD_DELETE</literal> and <literal>NULL
</literal>  in the <literal>mod_values</literal> field, the attribute is removed
from the entry.</para></listitem>
<listitem><para>If you specify <literal>LDAP_MOD_REPLACE</literal> and <literal>NULL
</literal>  in the <literal>mod_values</literal> field, the attribute is removed
from the entry.</para></listitem>
<listitem><para>If you specify <literal>LDAP_MOD_REPLACE</literal> and the
attribute does not exist in the entry, the attribute is added to the entry.</para>
</listitem>
<listitem><para>If you specify <literal>LDAP_MOD_ADD</literal> and the attribute
does not exist in the entry, the attribute is added to the entry.</para><para>Also,
if you are using the structure to add a new entry, you can specify <literal>0</literal> for
the <literal>mod_op</literal> field, unless you are adding binary values and
need to specify <literal>LDAP_MOD_BVALUES</literal>.</para></listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>mod_type</literal></para></entry>
<entry>
<para>The attribute type that you want to add, delete, or replace the values
of such as <literal>sn</literal> or <literal>telephoneNumber</literal>.</para>
</entry>
</row>
<row>
<entry>
<para><literal>mod_values</literal></para></entry>
<entry>
<para>A pointer to a <literal>NULL</literal> terminated array of string values
for the attribute.</para></entry>
</row>
<row>
<entry>
<para><literal>mod_bvalues</literal></para></entry>
<entry>
<para>A pointer to a <literal>NULL</literal> terminated array of  <olink targetptr="bdakg">berval</olink> structures for the attribute.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>If you&rsquo;ve allocated memory for the structures yourself, you should
free them when finished by calling the <olink targetptr="bdatu">ldap_mods_free</olink> function.
</para></sect3>
<sect3 id="gasou"><title>Example</title>
<para><olink targetptr="setup-ldapmod">Example 20&ndash;26</olink> sets up
an <literal>LDAPMod</literal> structure to change the email address of a user&rsquo;s
entry to <literal>bjensen@example.com</literal>.</para>
<example id="setup-ldapmod"><title>Setting Up an <structname>LDAPMod</structname> Structure
</title>
<programlisting>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] = &amp;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 );
}
...</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="LDAPpwdpolicy"><title><structname>LDAPpwdpolicy</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPpwdpolicy</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPpwdpolicy</structname></primary>
</indexterm>
<para>An <structname>LDAPpwdpolicy</structname> structure holds values concerning
the password policy governing a user account.</para>
<para>You fill this structure by passing it to the <olink targetptr="ldap-parse-pwdpolicy-control">ldap_parse_pwdpolicy_control</olink> function.
</para>
<sect3><title><structname>LDAPpwdpolicy</structname> Description</title>
<para>An <structname>LDAPpwdpolicy</structname> structure has the following
definition:</para>
<programlisting>typedef struct LDAPpwdpolicy {         /* password policy               */
        unsigned int pp_warning;       /* warning status                */
#define LDAP_PP_WARNING_NONE     0x00
#define LDAP_PP_WARNING_EXP      0x01
#define LDAP_PP_WARNING_GRACE    0x02
        int          pp_warning_info;  /* warning information           */
        int          pp_error;         /* error information             */
#define LDAP_PP_ERROR_NONE      -1     /* no error                      */
#define LDAP_PP_ERROR_EXPIRED    0     /* password expired              */
#define LDAP_PP_ERROR_LOCKED     1     /* account locked                */
#define LDAP_PP_ERROR_MUSTCHANGE 2     /* paasword has to be changed    */
#define LDAP_PP_ERROR_NOTMOD     3     /* modification not allowed      */
#define LDAP_PP_ERROR_OLDPASSWD  4     /* must provide old password     */
#define LDAP_PP_ERROR_NOQUALITY  5     /* insufficient password quality */
#define LDAP_PP_ERROR_TOOSHORT   6     /* password too short            */
#define LDAP_PP_ERROR_MINAGE     7     /* min age still in effect       */
#define LDAP_PP_ERROR_INHISTORY  8     /* password in history           */
} LDAPpwdpolicy;</programlisting>
<table frame="topbot" id="GBGIO"><title><structname>LDAPpwdpolicy</structname> Field
Descriptions</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><structfield>pp_warning</structfield></para></entry>
<entry>
<para>Warning code</para></entry>
</row>
<row>
<entry>
<para><structfield>pp_warning_info</structfield></para></entry>
<entry>
<para>If <structfield>pp_warning</structfield> is <literal>LDAP_PP_WARNING_EXP</literal>,
this holds the number of seconds before the password expires.</para>
<para>If <structfield>pp_warning</structfield> is <literal>LDAP_PP_WARNING_GRACE</literal>,
this holds the number of grace logins remaining.</para></entry>
</row>
<row>
<entry>
<para><structfield>pp_error</structfield></para></entry>
<entry>
<para>One of the following error codes:</para>
<itemizedlist>
<listitem><para><literal>LDAP_PP_ERROR_NONE</literal>, meaning no errors</para>
</listitem>
<listitem><para><literal>LDAP_PP_ERROR_EXPIRED</literal>, meaning the password
has expired, and must be reset</para></listitem>
<listitem><para><literal>LDAP_PP_ERROR_LOCKED</literal>, meaning the account
is locked</para></listitem>
<listitem><para><literal>LDAP_PP_ERROR_MUSTCHANGE</literal>, meaning the password
has been reset, and must be changed</para></listitem>
<listitem><para><literal>LDAP_PP_ERROR_NOTMOD</literal>, meaning the user
may not change the password</para></listitem>
<listitem><para><literal>LDAP_PP_ERROR_OLDPASSWD</literal>, meaning the old
password must be supplied for this operation</para></listitem>
<listitem><para><literal>LDAP_PP_ERROR_NOQUALITY</literal>, meaning the password
does not pass the server's password quality check</para></listitem>
<listitem><para><literal>LDAP_PP_ERROR_TOOSHORT</literal>, meaning the password
is too short</para></listitem>
<listitem><para><literal>LDAP_PP_ERROR_MINAGE</literal>, meaning the password
is too new to be modified, yet</para></listitem>
<listitem><para><literal>LDAP_PP_ERROR_INHISTORY</literal>, meaning the password
matches a password stored in the password history, and thus cannot be reused</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Memory Concerns</title>
<para>You allocate and free space for the <structname>LDAPpwdpolicy</structname> structure.
</para></sect3>
</sect2>
<sect2 id="bdama"><title><structname>LDAP_REALLOC_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_REALLOC_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_REALLOC_CALLBACK</structname></primary>
</indexterm>
<para>This callback function prototype of <olink targetptr="bdalw">ldap_memalloc_fns
</olink>  represents memory allocation.</para>
<sect3 id="gasob"><title>See Also</title>
<para><olink targetptr="bdalw">ldap_memalloc_fns</olink></para></sect3>
</sect2>
<sect2 id="bdamb"><title><structname>LDAP_REBINDPROC_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_REBINDPROC_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_REBINDPROC_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_REBINDPROC_CALLBACK</literal> specifies the prototype
for a callback function that retrieves authentication information when automatically
following referrals to other servers.</para>
<sect3 id="gaspg"><title>Description</title>
<para>If you define a function with this prototype and specify it when calling
the <olink targetptr="bdavh">ldap_set_rebind_proc</olink> function, the function
will be called by your LDAP client.</para>
<example id="gasom"><title><structname>LDAP_REBINDPROC_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_CALL LDAP_CALLBACK
  LDAP_REBINDPROC_CALLBACK)( LDAP *ld, char **dnp, char **passwdp,
  int *authmethodp, int freeit, void *arg);</programlisting>
</example>
</sect3>
<sect3 id="gasoz"><title>See Also</title>
<para><olink targetptr="bdavh">ldap_set_rebind_proc</olink></para></sect3>
</sect2>
<sect2 id="bdamc"><title><structname>LDAPsortkey</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPsortkey</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPsortkey</structname></primary>
</indexterm>
<para><literal>LDAPsortkey</literal> represents the criteria to be used by
a server control to sort search results before sending the results back to
the client.</para>
<note><para>Controls are part of the LDAP v3 and are used to extend the functionality
of an LDAP operation. The two types of controls described in the LDAP v3 are:</para>
<itemizedlist>
<listitem><para><emphasis>Server controls</emphasis> 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.</para>
</listitem>
<listitem><para><emphasis>Client controls</emphasis> 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&rsquo;ve specified in the
control. &DirectorySDKForC; does not currently support any client controls.</para>
</listitem>
</itemizedlist>
</note>
<sect3 id="gasop"><title>Description</title>
<example id="gasoc"><title><structname>LDAPsortkey</structname> Definition</title>
<programlisting>typedef struct LDAPsortkey {
  char *sk_attrtype;
  char *sk_matchruleoid;
  int sk_reverseorder;
} LDAPsortkey;</programlisting>
</example>
<table frame="topbot" id="gasnt"><title><structname>LDAPsortkey</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>sk_attrtype</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated string that specifies
the name of the attribute that you want to use for sorting.</para></entry>
</row>
<row>
<entry>
<para><literal>sk_matchruleoid</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated string that specifies
the object identifier (OID) of the matching rule that you want to use for
sorting.</para></entry>
</row>
<row>
<entry>
<para><literal>sk_reverseorder</literal></para></entry>
<entry>
<para>Specifies whether or not the results are sorted in reverse order. This
field can have one of the following values:</para>
<itemizedlist>
<listitem><para>A non-zero value specifies that the results should be sorted
in reverse order.</para></listitem>
<listitem><para><literal>0</literal> specifies that the results should be
sorted in normal (forward) order.</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>As an example, you can use <literal>LDAPsortkey</literal> to specify
that you want the server to sort search results by the <literal>roomNumber</literal> attribute.
To create an array of <literal>LDAPsortkey</literal> structures, you can call
the <olink targetptr="bdarf">ldap_create_sort_keylist</olink> function. To
free an array of  <literal>LDAPsortkey</literal> structures, you can call
the <olink targetptr="bdasg">ldap_free_sort_keylist</olink>  function.</para>
</sect3>
</sect2>
<sect2 id="bdamd"><title><structname>LDAP_TF_GET_ERRNO_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_GET_ERRNO_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_GET_ERRNO_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_GET_ERRNO_CALLBACK</literal> specifies the prototype
for a callback function to get the value of the <literal>errno</literal> variable
for a thread.</para>
<note><para>For more details on the <literal>errno</literal> variable, see <olink targetptr="bdamr">ldap_thread_fns</olink>.</para></note>
<sect3 id="gasnz"><title>Description</title>
<example id="gasov"><title><structname>LDAP_TF_GET_ERRNO_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_TF_GET_ERRNO_CALLBACK) ( void );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdame"><title><structname>LDAP_TF_GET_LDERRNO_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_GET_LDERRNO_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_GET_LDERRNO_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_GET_LDERRNO_CALLBACK</literal> specifies the prototype
for a callback function to retrieve the LDAP result code for an operation.</para>
<sect3 id="gasnv"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdamr">ldap_thread_fns</olink> structure, your callback function
is called when the <olink targetptr="bdasq">ldap_get_lderrno</olink> function
is called. The arguments of <olink targetptr="bdasq">ldap_get_lderrno</olink> are
passed to your function, and the value returned by your function is returned
by <olink targetptr="bdasq">ldap_get_lderrno</olink> .</para>
<note><para>For more details on the arguments and return values that your
function must use, see <olink targetptr="bdasq">ldap_get_lderrno</olink>.</para>
</note>
<example id="gasnm"><title><structname>LDAP_TF_GET_LDERRNO_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_TF_GET_LDERRNO_CALLBACK)( char **, char **, void * );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdamf"><title><structname>LDAP_TF_SET_ERRNO_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_SET_ERRNO_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_SET_ERRNO_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_SET_ERRNO_CALLBACK</literal> specifies the prototype
for a callback function to set the value of the <literal>errno</literal> variable
for a thread.</para>
<note><para>For more details on the <literal>errno</literal> variable, see <olink targetptr="bdamr">ldap_thread_fns</olink>.</para></note>
<sect3 id="gasoy"><title>Description</title>
<example id="gaspc"><title><structname>LDAP_TF_SET_ERRNO_CALLBACK</structname> Prototype
</title>
<programlisting>typedef void (LDAP_C LDAP_CALLBACK
  LDAP_TF_SET_ERRNO_CALLBACK)( int );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdamg"><title><structname>LDAP_TF_SET_LDERRNO_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_SET_LDERRNO_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_SET_LDERRNO_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_SET_LDERRNO_CALLBACK</literal> specifies the prototype
for a callback function to set the LDAP result code for an operation.</para>
<note><para>For more details on the arguments that your function must use,
see <olink targetptr="bdavf">ldap_set_lderrno</olink>.</para></note>
<sect3 id="gasnx"><title>Description</title>
<para>If you define a function with this prototype and set it in the  <olink targetptr="bdamr">ldap_thread_fns</olink> structure, your callback function
is called when the <olink targetptr="bdavf">ldap_set_lderrno</olink> function
is called. The arguments of <olink targetptr="bdavf">ldap_set_lderrno</olink> are
passed to your function.</para>
<example id="gaspe"><title><structname>LDAP_TF_SET_LDERRNO_CALLBACK</structname> Prototype
</title>
<programlisting>typedef void (LDAP_C LDAP_CALLBACK
  LDAP_TF_SET_LDERRNO_CALLBACK)( int, char *, char *, void * );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdamh"><title><structname>LDAP_TF_MUTEX_ALLOC_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_MUTEX_ALLOC_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_MUTEX_ALLOC_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_MUTEX_ALLOC_CALLBACK</literal> specifies the prototype
for a callback function to allocate a mutex.</para>
<sect3 id="gasol"><title>Description</title>
<example id="gasno"><title><structname>LDAP_TF_MUTEX_ALLOC_CALLBACK</structname> Prototype
</title>
<programlisting>typedef void *(LDAP_C LDAP_CALLBACK
  LDAP_TF_MUTEX_ALLOC_CALLBACK)( void );</programlisting>
</example>
</sect3>
<sect3 id="gasny"><title>See Also</title>
<para><olink targetptr="bdamr">ldap_thread_fns</olink></para></sect3>
</sect2>
<sect2 id="bdami"><title><structname>LDAP_TF_MUTEX_FREE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_MUTEX_FREE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_MUTEX_FREE_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_MUTEX_FREE_CALLBACK</literal> specifies the prototype
for a callback function to free a mutex.</para>
<sect3 id="gasos"><title>Description</title>
<example id="gasoe"><title><structname>LDAP_TF_MUTEX_FREE_CALLBACK</structname> Prototype
</title>
<programlisting>typedef void (LDAP_C LDAP_CALLBACK
  LDAP_TF_MUTEX_FREE_CALLBACK)( void * );</programlisting>
</example>
</sect3>
<sect3 id="gaspd"><title>See Also</title>
<para><olink targetptr="bdamr">ldap_thread_fns</olink></para></sect3>
</sect2>
<sect2 id="bdamj"><title><structname>LDAP_TF_MUTEX_LOCK_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_MUTEX_LOCK_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_MUTEX_LOCK_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_MUTEX_LOCK_CALLBACK</literal> specifies the prototype
for a callback function to lock a mutex.</para>
<sect3 id="gasof"><title>Description</title>
<example id="gasoi"><title><structname>LDAP_TF_MUTEX_LOCK_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_TF_MUTEX_LOCK_CALLBACK)( void * );</programlisting>
</example>
</sect3>
<sect3 id="gasog"><title>See Also</title>
<para><olink targetptr="bdamr">ldap_thread_fns</olink></para></sect3>
</sect2>
<sect2 id="bdamk"><title><structname>LDAP_TF_MUTEX_TRYLOCK_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_MUTEX_TRYLOCK_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_MUTEX_TRYLOCK_CALLBACK</structname></primary>
</indexterm>
<para>This function prototype is not supported in this release of &DirectorySDKForC;.
</para>
<sect3 id="bdaml"><title><structname>LDAP_TF_MUTEX_UNLOCK_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_MUTEX_UNLOCK_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_MUTEX_UNLOCK_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_MUTEX_UNLOCK_CALLBACK</literal> specifies the prototype
for a callback function to unlock a mutex.</para></sect3>
<sect3 id="gasor"><title>Description</title>
<example id="gasph"><title><structname>LDAP_TF_MUTEX_UNLOCK_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_TF_MUTEX_UNLOCK_CALLBACK)( void * );</programlisting>
</example>
</sect3>
<sect3 id="gasoq"><title>See Also</title>
<para><olink targetptr="bdamr">ldap_thread_fns</olink></para></sect3>
</sect2>
<sect2 id="bdamm"><title><structname>LDAP_TF_SEMA_ALLOC_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_SEMA_ALLOC_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_SEMA_ALLOC_CALLBACK</structname></primary>
</indexterm>
<para>This function prototype is not supported in this release of &DirectorySDKForC;.
</para>
<sect3 id="bdamn"><title><structname>LDAP_TF_SEMA_FREE_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_SEMA_FREE_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_SEMA_FREE_CALLBACK</structname></primary>
</indexterm>
<para>This function prototype is not supported in this release of &DirectorySDKForC;.
</para></sect3>
</sect2>
<sect2 id="bdamo"><title><structname>LDAP_TF_SEMA_POST_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_SEMA_POST_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_SEMA_POST_CALLBACK</structname></primary>
</indexterm>
<para>This function prototype is not supported in this release of &DirectorySDKForC;.
</para>
<sect3 id="bdamp"><title><structname>LDAP_TF_SEMA_WAIT_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_SEMA_WAIT_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_SEMA_WAIT_CALLBACK</structname></primary>
</indexterm>
<para>This function prototype is not supported in this release of &DirectorySDKForC;.
</para></sect3>
</sect2>
<sect2 id="bdamq"><title><structname>LDAP_TF_THREADID_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_TF_THREADID_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_TF_THREADID_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_TF_THREADID_CALLBACK</literal> specifies the prototype
for a callback function to return an identifier that is unique to the calling
thread, much like the POSIX <function>pthread_self</function> function does.</para>
<sect3 id="gason"><title>Description</title>
<example id="gasnw"><title><structname>LDAP_TF_THREADID_CALLBACK</structname> Prototype
</title>
<programlisting>typedef void *(LDAP_C LDAP_CALLBACK
  LDAP_TF_THREADID_CALLBACK)( void );</programlisting>
</example>
</sect3>
<sect3 id="gasnq"><title>See Also</title>
<para><olink targetptr="bdamr">ldap_thread_fns</olink></para></sect3>
</sect2>
<sect2 id="bdamr"><title><structname>ldap_thread_fns</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>ldap_thread_fns</structname></secondary>
</indexterm><indexterm>
<primary><structname>ldap_thread_fns</structname></primary>
</indexterm>
<para>The <literal>ldap_thread_fns</literal> structure contains a set of pointers
to functions that you want to use when write a multithreaded client.</para>
<sect3 id="gasnn"><title>Description</title>
<example id="gasow"><title><structname>ldap_thread_fns</structname> Structure
Definition</title>
<programlisting>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;
};</programlisting>
</example>
<table frame="topbot" id="gasox"><title><structname>ldap_thread_fns</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ltf_mutex_alloc</literal></para></entry>
<entry>
<para>Function pointer for allocating a mutex. This function is called by
the client when needed if the function pointer is not <literal>NULL</literal>.
The function must have the prototype specified by <olink targetptr="bdamh">LDAP_TF_MUTEX_ALLOC_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_mutex_free</literal></para></entry>
<entry>
<para>Function pointer for freeing a mutex. This function is called by the
client when needed if the function pointer is not <literal>NULL</literal>.
The function must have the prototype specified by <olink targetptr="bdami">LDAP_TF_MUTEX_FREE_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_mutex_lock</literal></para></entry>
<entry>
<para>Function pointer for locking critical sections of code. This function
is called by the client when needed if the function pointer is not <literal>NULL</literal>.
The function must have the prototype specified by <olink targetptr="bdamj">LDAP_TF_MUTEX_LOCK_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_mutex_unlock</literal></para></entry>
<entry>
<para>Function pointer for unlocking critical sections of code. This function
is called by the client when needed if the function pointer is not <literal>NULL</literal>.
The function must have the prototype specified by <olink targetptr="bdaml">LDAP_TF_MUTEX_UNLOCK_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_get_errno</literal></para></entry>
<entry>
<para>Function pointer for getting the value of the <symbol>errno</symbol> variable.
This function is called by the client when needed if the function pointer
is not <literal>NULL</literal>.</para>
<para>In a threaded environment, <literal>errno</literal> 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 <literal>libldap</literal> library
does not know what method your code and threading environment will use to
get the value of <literal>errno</literal> for each thread, it calls this function
to obtain the value. The function must have the prototype specified by <olink targetptr="bdamd">LDAP_TF_GET_ERRNO_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_set_errno</literal></para></entry>
<entry>
<para>Function pointer for setting the value of the <symbol>errno</symbol> variable.
This function is called by the client when needed if the function pointer
is not <literal>NULL</literal>.</para>
<para>In a threaded environment, <literal>errno</literal> 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 <literal>libldap</literal> library
does not know what method your code and threading environment will use to
get the value of <literal>errno</literal> for each thread, it calls this function
to obtain the value. The function must have the prototype specified by <olink targetptr="bdamf">LDAP_TF_SET_ERRNO_CALLBACK</olink>.</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_get_lderrno</literal></para></entry>
<entry>
<para>Function pointer for getting error values from calls to functions in
the <literal>libldap</literal> library. This function is called by the client
as needed if the function pointer isn&rsquo;t  <literal>NULL</literal>. If
this function pointer is not set, the <literal>libldap</literal> library records
these errors in fields in the <olink targetptr="bdakj">LDAP</olink> structure.
The function must have the prototype specified by <olink targetptr="bdame">LDAP_TF_GET_LDERRNO_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_set_lderrno</literal></para></entry>
<entry>
<para>Function pointer for setting error values from calls to functions in
the <literal>libldap</literal> library. This function is called by the client
as needed if the function pointer is not  <literal>NULL</literal>. If this
function pointer is not set, the <literal>libldap</literal> library records
these errors in fields in the <olink targetptr="bdakj">LDAP</olink> structure.
The function must have the prototype specified by <olink targetptr="bdamg">LDAP_TF_SET_LDERRNO_CALLBACK
</olink> .</para></entry>
</row>
<row>
<entry>
<para><literal>ltf_lderrno_arg</literal></para></entry>
<entry>
<para>Additional parameter passed to the functions for getting and setting
error values from calls to functions in the <literal>libldap</literal> library. <literal>
(*ltf_get_lderrno)</literal> and  <literal>(*ltf_set_lderrno)</literal> identify
these functions.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdams"><title><structname>LDAPURLDesc</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPURLDesc</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPURLDesc</structname></primary>
</indexterm>
<para><literal>LDAPURLDesc</literal> is a structure that represents the components
of an LDAP URL.</para>
<sect3 id="gasnu"><title>Description</title>
<para>LDAP URLs have the following syntax:</para>
<programlisting>ldap://<replaceable>host</replaceable>:<replaceable>port</replaceable>/
<replaceable>dn</replaceable>?<replaceable>attributes</replaceable>?<replaceable>
scope</replaceable>?(
<replaceable>filter</replaceable>)</programlisting>
<para>Where, for example:</para>
<programlisting>ldap://ldap.example.com/c=US?o,description?one?(o=Sales)</programlisting>
<para>Calling the <olink targetptr="bdawk">ldap_url_parse</olink> function
creates an <literal>LDAPURLDesc</literal> structure with the components of
the URL.</para>
<example id="gasqe"><title><structname>LDAPURLDesc</structname> Definition</title>
<programlisting>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</programlisting>
</example>
<table frame="topbot" id="gasrf"><title><structname>LDAPURLDesc</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>lud_host</literal></para></entry>
<entry>
<para>Name of the host in the URL.</para></entry>
</row>
<row>
<entry>
<para><literal>lud_port</literal></para></entry>
<entry>
<para>Number of the port in the URL.</para></entry>
</row>
<row>
<entry>
<para><literal>lud_dn</literal></para></entry>
<entry>
<para>Distinguished name in the URL. This <emphasis>base entry</emphasis> DN
identifies the starting point of the search.</para></entry>
</row>
<row>
<entry>
<para><literal>lud_attrs</literal></para></entry>
<entry>
<para>Pointer to a <literal>NULL</literal> terminated list of the attributes
specified in the URL.</para></entry>
</row>
<row>
<entry>
<para><literal>lud_scope</literal></para></entry>
<entry>
<para>Integer representing the scope of the search specified in the URL:</para>
<itemizedlist>
<listitem><para><literal>LDAP_SCOPE_BASE</literal> specifies a search of the
base entry.</para></listitem>
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> specifies a search
of all entries one level under the base entry (not including the base entry).</para>
</listitem>
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> specified a search of
all entries at all levels under the base entry (including the base entry).</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>
<para><literal>lud_filter</literal></para></entry>
<entry>
<para>Search filter included in the URL.</para></entry>
</row>
<row>
<entry>
<para><literal>lud_options</literal></para></entry>
<entry>
<para>Options; if <literal>LDAP_URL_OPT_SECURE</literal>, indicates that the
protocol is <literal>ldaps://</literal> instead of <literal>ldap://</literal>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>For example, suppose you pass the following URL to the  <olink targetptr="bdawk">ldap_url_parse</olink> function:</para>
<programlisting>ldap://ldap.example.com:5000/dc=example,dc=com?cn,mail, \
  telephoneNumber?sub?(sn=Jensen)</programlisting>
<para>The resulting <literal>LDAPURLDesc</literal> structure-<literal>ludpp</literal>,
in this example-will contain the values in <olink targetptr="ldapurldesc-parsed-example">Table 20&ndash;27</olink>.</para>
<table frame="topbot" id="ldapurldesc-parsed-example"><title><structname>LDAPURLDesc
</structname> Parsed URL Values</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Component</para></entry>
<entry>
<para>Value</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ludpp->lud_host</literal></para></entry>
<entry>
<para><literal>ldap.example.com</literal></para></entry>
</row>
<row>
<entry>
<para><literal>ludpp->lud_port</literal></para></entry>
<entry>
<para><literal>5000</literal></para></entry>
</row>
<row>
<entry>
<para><literal>ludpp->lud_dn</literal></para></entry>
<entry>
<para><literal>dc=example,dc=com</literal></para></entry>
</row>
<row>
<entry>
<para><literal>ludpp->lud_attrs[0]</literal></para></entry>
<entry>
<para><literal>cn</literal></para></entry>
</row>
<row>
<entry>
<para><literal>ludpp->lud_attrs[1]</literal></para></entry>
<entry>
<para><literal>mail</literal></para></entry>
</row>
<row>
<entry>
<para><literal>ludpp->lud_attrs[2]</literal></para></entry>
<entry>
<para><literal>telephoneNumber</literal></para></entry>
</row>
<row>
<entry>
<para><literal>ludpp->lud_attrs[3]</literal></para></entry>
<entry>
<para><literal>NULL</literal></para></entry>
</row>
<row>
<entry>
<para><literal>ludpp->lud_scope</literal></para></entry>
<entry>
<para><literal>LDAP_SCOPE_SUBTREE</literal></para></entry>
</row>
<row>
<entry>
<para><literal>ludpp->lud_filter</literal></para></entry>
<entry>
<para><literal>(sn=Jensen)</literal></para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>To free the <literal>LDAPURLDesc</literal> structure, call the  <olink targetptr="bdasi">ldap_free_urldesc</olink> routine.</para></sect3>
</sect2>
<sect2 id="ldapuserstatus"><title><structname>LDAPuserstatus</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPuserstatus</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPuserstatus</structname></primary>
</indexterm>
<para>An <structname>LDAPuserstatus</structname> structure holds the values
concerning the status of a user account.</para>
<para>You fill this structure by passing it to the <olink targetptr="ldap-parse-userstatus-control">ldap_parse_userstatus_control</olink> function.
</para>
<sect3><title><structname>LDAPuserstatus</structname> Description</title>
<para>An <structname>LDAPuserstatus</structname> structure has the following
definition:</para>
<programlisting>typedef struct LDAPuserstatus {     /* user account availability   */
        unsigned int us_available;  /* availability status         */
#define LDAP_US_ACCOUNT_USABLE      0
#define LDAP_US_ACCOUNT_NOT_USABLE  1
        int          us_expire;     /* will expire in seconds      */
        int          us_inactive;   /* boolean inactivation status */
#define LDAP_US_ACCOUNT_ACTIVE      0
#define LDAP_US_ACCOUNT_INACTIVE    1
        int          us_reset;      /* boolean password reset      */
#define LDAP_US_ACCOUNT_NOT_RESET   0
#define LDAP_US_ACCOUNT_RESET       1
        int          us_expired;    /* boolean password expired    */
#define LDAP_US_ACCOUNT_NOT_EXPIRED 0
#define LDAP_US_ACCOUNT_EXPIRED     1
        int          us_remaining;  /* remaining logins            */
        int          us_seconds;    /* will unlock in seconds      */
} LDAPuserstatus;</programlisting>
<table frame="topbot" id="gbgbl"><title><structname>LDAPuserstatus</structname> Field
Descriptions</title>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
colwidth="50*">
<thead>
<row rowsep="1">
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><structfield>us_available</structfield></para></entry>
<entry>
<para>Whether the account is currently usable</para></entry>
</row>
<row>
<entry>
<para><structfield>us_expire</structfield></para></entry>
<entry>
<para>Number of seconds before the password expires</para>
<para><literal>-1</literal> means the password is not set to expire at all.</para>
</entry>
</row>
<row>
<entry>
<para><structfield>us_inactive</structfield></para></entry>
<entry>
<para>Whether the account is locked</para></entry>
</row>
<row>
<entry>
<para><structfield>us_reset</structfield></para></entry>
<entry>
<para>Whether the password has been reset</para></entry>
</row>
<row>
<entry>
<para><structfield>us_expired</structfield></para></entry>
<entry>
<para>Whether the password has expired</para></entry>
</row>
<row>
<entry>
<para><structfield>us_remaining</structfield></para></entry>
<entry>
<para>Number of remaining grace logins</para></entry>
</row>
<row>
<entry>
<para><structfield>us_seconds</structfield></para></entry>
<entry>
<para>Number of seconds before the server unlocks the account</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3><title>Memory Concerns</title>
<para>You allocate and free space for the <structname>LDAPuserstatus</structname> structure.
</para></sect3>
</sect2>
<sect2 id="bdamt"><title><structname>LDAP_VALCMP_CALLBACK</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAP_VALCMP_CALLBACK</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAP_VALCMP_CALLBACK</structname></primary>
</indexterm>
<para><literal>LDAP_VALCMP_CALLBACK</literal> specifies the prototype for
a callback function to sort a specified set of values.</para>
<sect3 id="gaspx"><title>Description</title>
<para>If you define a function with this prototype and specify it when calling
the <olink targetptr="bdavl">ldap_sort_strcasecmp</olink> function, the function
will be called by your LDAP client.</para>
<example id="gaspw"><title><structname>LDAP_VALCMP_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK
  LDAP_VALCMP_CALLBACK)(const char**, const char**);</programlisting>
</example>
<para><olink targetptr="bdavm">ldap_sort_values</olink> requires a function
pointer that matches the signature defined by this type. <olink targetptr="bdavl">
ldap_sort_strcasecmp</olink>  is a value comparison function defined using
this type which can therefore be passed to <olink targetptr="bdavm">ldap_sort_values
</olink>.</para></sect3>
<sect3 id="gasqi"><title>See Also</title>
<para><olink targetptr="bdavm">ldap_sort_values</olink>,  <olink targetptr="bdavl">ldap_sort_strcasecmp</olink></para></sect3>
</sect2>
<sect2 id="bdamu"><title><structname>LDAPVersion</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPVersion</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPVersion</structname></primary>
</indexterm>
<para>The <literal>LDAPVersion</literal> structure contains version information
about &DirectorySDKForC;.</para>
<note><para>The <literal>LDAPVersion</literal> type is deprecated; it is documented
here only for backward compatibility. Instead, use the <olink targetptr="bdass">ldap_get_option
</olink>  function with the <literal>LDAP_OPT_API_INFO</literal> option and
retrieve an <olink targetptr="bdakl">LDAPAPIInfo</olink> structure.</para>
</note>
<sect3 id="gasqf"><title>Description</title>
<para>Call the <olink targetptr="bdaxe">ldap_version</olink> function to return
a pointer to an <literal>LDAPVersion</literal> structure containing version
information.</para>
<example id="gaspp"><title><structname>LDAPVersion</structname> Definition</title>
<programlisting>typedef struct _LDAPVersion {
  int sdk_version;
  int protocol_version;
  int SSL_version;
  int security_level;
} LDAPVersion;</programlisting>
</example>
<table frame="topbot" id="gasrg"><title><structname>LDAPVersion</structname> Field
Definitions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>sdk_version</literal></para></entry>
<entry>
<para>Version number of &DirectorySDKForC; multiplied by 100. For example,
the value 600 in this field represents version 6.0.</para></entry>
</row>
<row>
<entry>
<para><literal>protocol_version</literal></para></entry>
<entry>
<para>Highest supported LDAP protocol version multiplied by 100. For example,
the value 300 in this field represents LDAP v3.</para></entry>
</row>
<row>
<entry>
<para><literal>SSL_version</literal></para></entry>
<entry>
<para>Supported SSL version multiplied by 100. For example, the value 300
in this field represents SSL 3.0).</para></entry>
</row>
<row>
<entry>
<para><literal>security_level</literal></para></entry>
<entry>
<para>Level of encryption supported in bits. For example, 128 for US domestic
or 40 for export.</para>
<para>If SSL is not enabled, the value of this field is <literal>LDAP_SECURITY_NONE
</literal> .</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdamv"><title><structname>LDAPVirtualList</structname></title>
<indexterm>
<primary>C SDK data types</primary>
<secondary><structname>LDAPVirtualList</structname></secondary>
</indexterm><indexterm>
<primary><structname>LDAPVirtualList</structname></primary>
</indexterm>
<para><literal>LDAPVirtualList</literal> specifies the information that can
be used to create a <emphasis>virtual list view</emphasis> control.</para>
<sect3 id="gasrc"><title>Description</title>
<para>A <emphasis>virtual list view</emphasis> control is a LDAP v3 control
designed to allow the client to retrieve subsets of search results to display
in a  <emphasis>virtual list box</emphasis>. A <emphasis>virtual list box</emphasis> 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.</para>
<para>After you create an <literal>LDAPVirtualList</literal> structure and
specify values for its fields, you can create the virtual list view control
by calling the function <olink targetptr="bdarg">ldap_create_virtuallist_control</olink>.
You can pass this control and a server-side sorting control-created by calling
the <olink targetptr="bdarf">ldap_create_sort_keylist</olink> function and
the  <olink targetptr="bdare">ldap_create_sort_control</olink> function-to
the <olink targetptr="bdauz">ldap_search_ext</olink>  or <olink targetptr="bdava">
ldap_search_ext_s</olink> function. To get the virtual list view response
control sent back from the server, call the <olink targetptr="bdaun">ldap_parse_result
</olink> function to get the list of controls returned by the server, then
call the <olink targetptr="bdauq">ldap_parse_virtuallist_control</olink> 
function to retrieve information from the control. End users can display different
sections of the list by scrolling up or down.</para>
<note><para>The object identifier (OID) for this control is OID <literal>2.16.840.1.113730.3.4.9
</literal> , or <literal>LDAP_CONTROL_VLVREQUEST</literal> as defined in  <literal>
ldap.h</literal>. It is supported by &cnDirectoryServer;.</para></note>
<para>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:</para>
<itemizedlist>
<listitem><para>The entry in the list that is currently selected.</para>
</listitem>
<listitem><para>The number of entries to be displayed in the list before the
selected item.</para></listitem>
<listitem><para>The number of entries to be displayed in the list after the
selected entry.</para><para>The currently selected entry can be identified
in one of the following ways:</para></listitem>
<listitem><para>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.</para></listitem>
<listitem><para>By the value of the entry in which case, the control specifies
that value.</para><para>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:</para></listitem>
<listitem><para>The selected entry is the 20th entry from the top&mdash;in
other words, the index or offset of the entry is 20&mdash;of a list of 100.</para>
</listitem>
<listitem><para>Get 5 entries before the selected entry in the list (entries
15 - 19).</para></listitem>
<listitem><para>Get 4 entries after the selected entry in the list (entries
21 - 24).</para><para>As another example, a virtual list view control might
specify that you want to retrieve a subset of entries that start with the
letter <literal>c</literal> or a later letter in the alphabet. The control
might specify the following information:</para></listitem>
<listitem><para>The selected entry is the first entry that starts with the
letter  <literal>c</literal>. The size of the list is not relevant in determining
the selected entry in this case.</para></listitem>
<listitem><para>Get 5 entries before the selected entry in the list.</para>
</listitem>
<listitem><para>Get 4 entries after the selected entry in the list.</para>
</listitem>
</itemizedlist>
<example id="gasqa"><title><structname>LDAPVirtualList</structname> Definition</title>
<programlisting>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;</programlisting>
</example>
<table frame="topbot" id="gaspu"><title><structname>LDAPVirtualList</structname> Field
Descriptions</title>
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
colwidth="50*">
<thead>
<row>
<entry>
<para>Field</para></entry>
<entry>
<para>What It Contains</para></entry>
</row>
</thead>
<tbody>
<row rowsep="1">
<entry>
<para><literal>ldvlist_before_count</literal></para></entry>
<entry>
<para>Number of entries before the selected entry that you want to retrieve.</para>
</entry>
</row>
<row>
<entry>
<para><literal>ldvlist_after_count</literal></para></entry>
<entry>
<para>Number of entries after the selected entry that you want to retrieve.</para>
</entry>
</row>
<row>
<entry>
<para><literal>ldvlist_attrvalue</literal></para></entry>
<entry>
<para>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 <literal>NULL</literal>, the <literal>ldvlist_index</literal> and <literal>
ldvlist_size</literal>  fields are used to determine the selected entry instead.</para>
</entry>
</row>
<row>
<entry>
<para><literal>ldvlist_index</literal></para></entry>
<entry>
<para>If the <literal>ldvlist_attrvalue</literal> field is <literal>NULL</literal>,
specifies the offset or index of the selected entry in the list. This field
is used in conjunction with the <literal>ldvlist_size</literal> field to identify
the selected entry.</para></entry>
</row>
<row>
<entry>
<para><literal>ldvlist_size</literal></para></entry>
<entry>
<para>If the <literal>ldvlist_attrvalue</literal> field is <literal>NULL</literal>,
specifies the total number items in the list. This field is used in conjunction
with the <literal>ldvlist_index</literal> field to identify the selected entry.</para>
</entry>
</row>
<row>
<entry>
<para><literal>ldvlist_extradata</literal></para></entry>
<entry>
<para>Reserved for application-specific use. This data is not used in the
virtual list view control.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 id="bdamw"><title><structname>LDAP_X_EXTIOF_CLOSE_CALLBACK</structname></title>
<para>This specifies the prototype for an extended I/O callback function to
close a socket connection.</para>
<sect3 id="gasqb"><title>Description</title>
<example id="gasps"><title><structname>LDAP_X_EXTIOF_CLOSE_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_CLOSE_CALLBACK )(
     int s, void *arg );</programlisting>
</example>
</sect3>
<sect3 id="gasqz"><title>See Also</title>
<para><olink targetptr="bdana">ldap_x_ext_io_fns</olink></para></sect3>
</sect2>
<sect2 id="bdamx"><title><structname>LDAP_X_EXTIOF_CONNECT_CALLBACK</structname></title>
<para>This specifies the prototype for an extended I/O callback function to
open a socket connection.</para>
<sect3 id="gasqh"><title>Description</title>
<para><literal>LDAP_X_EXTIOF_CONNECT_CALLBACK</literal> takes a <literal>timeout</literal> parameter
whose value in milliseconds can be set by calling <olink targetptr="bdavg">ldap_set_option
</olink> .</para>
<example id="gasrd"><title><structname>LDAP_X_EXTIOF_CONNECT_CALLBACK</structname> Prototype
</title>
<programlisting>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 );</programlisting>
</example>
</sect3>
<sect3 id="gasrh"><title>See Also</title>
<para><olink targetptr="bdana">ldap_x_ext_io_fns</olink></para></sect3>
</sect2>
<sect2 id="bdamy"><title><structname>LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK</structname></title>
<para>This specifies the prototype for an extended I/O callback function to
dispose of a session handle.</para>
<sect3 id="gasri"><title>Description</title>
<para><literal>LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK</literal> is called right
before the LDAP session handle and its contents are destroyed during  <olink targetptr="bdawh">ldap_unbind</olink>. The value of the <literal>arg</literal> parameter
passed to the callback is always the default one.</para>
<example id="gaspm"><title><structname>LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK</structname> Prototype
</title>
<programlisting>typedef void (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK)(
     LDAP *ld, void *arg );</programlisting>
</example>
</sect3>
<sect3 id="gasqd"><title>See Also</title>
<para><olink targetptr="bdana">ldap_x_ext_io_fns</olink></para></sect3>
</sect2>
<sect2 id="bdamz"><title><structname>LDAP_X_EXTIOF_NEWHANDLE_CALLBACK</structname></title>
<para>This specifies the prototype for an extended I/O callback function to
define a new session handle.</para>
<sect3 id="gasqt"><title>Description</title>
<para><literal>LDAP_X_EXTIOF_NEWHANDLE_CALLBACK</literal> is called right
after the LDAP session handle is created during <olink targetptr="bdasv">ldap_init
</olink>. The value of the <literal>arg</literal> parameter passed to the
callback is always the default one. If the callback returns anything other
than  <errorcode>LDAP_SUCCESS</errorcode>, the session handle allocation fails.</para>
<example id="gasra"><title><structname>LDAP_X_EXTIOF_NEWHANDLE_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_NEWHANDLE_CALLBACK)(
     LDAP *ld, void *arg );</programlisting>
</example>
</sect3>
<sect3 id="gaspo"><title>See Also</title>
<para><olink targetptr="bdana">ldap_x_ext_io_fns</olink></para></sect3>
</sect2>
<sect2 id="bdana"><title><structname>ldap_x_ext_io_fns</structname></title>
<para>This is a structure to hold extended I/O function pointers.</para>
<example id="gasql"><title><structname>ldap_x_ext_io_fns</structname> Definition</title>
<programlisting>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)</programlisting>
</example>
</sect2>
<sect2 id="bdanb"><title><structname>LDAP_X_EXTIOF_POLL_CALLBACK</structname></title>
<para>This specifies the prototype for an extended I/O callback function to
close a socket connection.</para>
<sect3 id="gasqx"><title>Description</title>
<para>The <literal>LDAP_X_EXTIOF_POLL_CALLBACK</literal> interface is provided
instead of a standard <function>select</function> interface. The time out
is in milliseconds. The value of the <parameter>arg</parameter> parameter
passed to the callback is always the default one.</para>
<example id="gasqp"><title><structname>LDAP_X_EXTIOF_POLL_CALLBACK</structname> Prototype
</title>
<programlisting>typedef int (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_POLL_CALLBACK)(
     LDAP_X_PollFD fds[], int nfds, int timeout /* milliseconds */,
     void *arg );</programlisting>
</example>
</sect3>
<sect3 id="gaspk"><title>See Also</title>
<para><olink targetptr="bdana">ldap_x_ext_io_fns</olink>,  <olink targetptr="bdand">LDAP_X_PollFD</olink></para></sect3>
</sect2>
<sect2 id="bdanc"><title><structname>ldap_x_hostlist_status</structname></title>
<para>This structure contains utility functions for parsing space-separated
host lists.</para>
<sect3 id="gasqw"><title>Description</title>
<example id="gasqo"><title><structname>ldap_x_hostlist_status</structname> Definition
</title>
<programlisting>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 );</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="bdand"><title><structname>LDAP_X_PollFD</structname></title>
<para><?Pub Caret1>This is a structure to hold the set of file descriptors
that will be surveyed for I/O by the <olink targetptr="bdanb">LDAP_X_EXTIOF_POLL_CALLBACK
</olink>.</para>
<sect3 id="gasqj"><title>Description</title>
<example id="gasqn"><title><structname>LDAP_X_PollFD</structname> Structure
Definition</title>
<programlisting>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;</programlisting>
</example>
</sect3>
</sect2>
</sect1>
</chapter>
