<!--

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="csdk-using"><title>About &DirectorySDKForC;</title>
<highlights>
<itemizedlist>
<para>This chapter introduces &DirectorySDKForC; and covers the following
topics:</para>
<listitem><para><olink targetptr="bdaas">Overview of Directory SDK for C</olink></para>
</listitem>
<listitem><para><olink targetptr="bdaaw">Files Provided With Directory SDK
for C</olink></para></listitem>
<listitem><para><olink targetptr="bdabi">Compiling Applications with Directory
SDK for C</olink></para></listitem>
<listitem><para><olink targetptr="bdabp">Sample Programs for Directory SDK
for C</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="bdaas"><title>Overview of &DirectorySDKForC;</title>
<indexterm>
<primary>C SDK</primary>
<secondary>overview of</secondary>
</indexterm>
<para>&DirectorySDKForC; includes the C libraries for the LDAP API as well
as sample code that demonstrates how to call many functions. The APIs are
defined by the header files that declare all of the functions, data types,
and code values in the SDK. You use the functions in this API to write C or
C++ client applications that take full advantage of server capabilities.</para>
<para>The APIs are built around core functions of the LDAP v2 and v3 standards.
Therefore, the APIs can be used to interact with any conforming LDAP server.
This API conforms to the standard that is proposed in <citetitle>The C LDAP
Application Programming Interface</citetitle>.</para>
<sect2 id="bdaat"><title>LDAP API</title>
<indexterm>
<primary>LDAP Application Programming Interface (API)</primary>
<see>LDAP API</see></indexterm><indexterm>
<primary>LDAP API</primary>
</indexterm><indexterm>
<primary>APIs</primary>
<secondary>LDAP</secondary>
</indexterm>
<para><ulink url="http://www.ietf.org/rfc/rfc4511.txt" type="text_url">RFC
4511</ulink>, <citetitle>Lightweight Directory Access Protocol (v3)</citetitle>,
defines a set of operations to access data in an LDAP v3 compliant directory
server. The functionality implemented in &DirectorySDKForC; closely follows
these operations because a C API is defined for each operation.</para>
<itemizedlist>
<para>With the C API, you can enable client applications to connect to LDAP
v3 compliant directory servers. Client applications can then perform both
standard and extended LDAP operations such as the following:</para>
<listitem><para>Search for and retrieve a list of entries.</para></listitem>
<listitem><para>Add new entries to the database.</para></listitem>
<listitem><para>Update existing directory entries.</para></listitem>
<listitem><para>Delete entries.</para></listitem>
<listitem><para>Rename entries.</para><para>For example, if you are writing
an email application, you can use the functions in the API to retrieve email
addresses from an LDAP server.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="bdaau"><title>Synchronous and Asynchronous Operations</title>
<indexterm>
<primary>C SDK</primary>
<secondary>synchronous functions</secondary>
</indexterm><indexterm>
<primary>C SDK</primary>
<secondary>asynchronous functions</secondary>
</indexterm><indexterm>
<primary>operations</primary>
<secondary>asynchronous</secondary>
</indexterm><indexterm>
<primary>operations</primary>
<secondary>synchronous</secondary>
</indexterm>
<para>The API functions allow you to perform LDAP operations synchronously
or asynchronously. The only differences between these two options are in the
calling convention. The LDAP exchanges are identical.</para>
<itemizedlist>
<listitem><para>Call a synchronous function to wait for the operation to complete
before receiving the return value of a function.</para></listitem>
<listitem><para>Call an asynchronous function to perform other work while
waiting for an operation to complete. Your application must then poll for
results.</para><para>For more information, see <olink targetptr="bdabq">Synchronous
Examples</olink>, and <olink targetptr="bdabr">Asynchronous Examples</olink>.<?Pub
Caret></para></listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="bdaaw"><title>Files Provided With Directory SDK for C</title>
<indexterm>
<primary>C SDK</primary>
<secondary>files installed</secondary>
</indexterm>
<para>&DirectorySDKForC; includes a number of sample files, headers, libraries,
and tools. This section helps you to locate the files. All locations are relative
to the directory where the software is installed, which depends on your operating
system.</para>
<table frame="topbot" pgwide="1"><title>&DirectorySDKForC; Content</title>
<tgroup cols="2"><colspec colnum="1" colwidth="19.69*"><colspec colnum="2"
colwidth="80.31*">
<thead>
<row>
<entry>
<para>Directory Location</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><filename>etc/</filename></para></entry>
<entry>
<para>Contains miscellaneous files for you to use. The files are described
in <olink targetptr="bdabc">Miscellaneous Files</olink></para></entry>
</row>
<row>
<entry>
<para><filename>examples/</filename></para></entry>
<entry>
<para>Contains sample source code and Makefiles for LDAP clients. See the <literal>
README</literal> file in this directory for more information.</para></entry>
</row>
<row>
<entry>
<para><filename>include/</filename></para></entry>
<entry>
<para>Contains the header files. You must include the files in this directory
in your client source files. The header files are described in <olink targetptr="bdaax">Directory SDK for C Header Files</olink></para></entry>
</row>
<row>
<entry>
<para><filename>include-nspr/</filename></para></entry>
<entry>
<para>Contains Netscape Portable Runtime (NSPR) header files. NSPR provides
a platform-neutral API for system&mdash;level and <literal>libc</literal>&mdash;style
functions.</para></entry>
</row>
<row>
<entry>
<para><filename>include-private/</filename></para></entry>
<entry>
<para>Contains private header files that are not documented in this guide.</para>
</entry>
</row>
<row>
<entry>
<para><filename>lib/</filename></para></entry>
<entry>
<para>Contains the C library files. The specific library used is dependent
on the type of application you are building. For details see <olink targetptr="bdabd">Directory SDK for C Libraries</olink>.</para></entry>
</row>
<row>
<entry>
<para><filename>lib-private/</filename></para></entry>
<entry>
<para>Contains private libraries that are not documented in this guide.</para>
</entry>
</row>
<row>
<entry>
<para><filename>tools/</filename></para></entry>
<entry>
<para>Contains the LDAP command-line tools. To use these applications, you
must ensure that the tools can find the LDAP API shared library or dynamic
link library.</para></entry>
</row>
</tbody>
</tgroup>
</table>
<sect2 id="bdaax"><title>&DirectorySDKForC; Header Files</title>
<indexterm>
<primary>C SDK</primary>
<secondary>header files</secondary>
</indexterm><indexterm>
<primary>header files</primary>
<secondary>C SDK</secondary>
</indexterm>
<para>The following table describes &DirectorySDKForC; header files that
are in the <filename>include/</filename> directory. </para>
<note><para>All locations are relative to the directory where the software
is installed, which depends on your operating system.</para></note>
<table frame="topbot" pgwide="1" id="csdk-headers"><title>&DirectorySDKForC; Header
Files</title>
<tgroup cols="2"><colspec colnum="1" colwidth="22.89*"><colspec colnum="2"
colwidth="77.11*">
<thead>
<row>
<entry>
<para>Header File</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><filename>disptmpl.h</filename></para></entry>
<entry>
<para>A header file related to the templates (<literal>ldaptemplates.conf</literal>).
</para></entry>
</row>
<row>
<entry>
<para><literal>lber.h</literal></para></entry>
<entry>
<para>Contains prototypes for the standard Basic Encoding Rules (BER) functions,
structures, and defines. For details see <olink targetptr="bdaaz">lber.h Header
File</olink></para></entry>
</row>
<row>
<entry>
<para><filename>ldap-deprecated.h</filename></para></entry>
<entry>
<para>Contains deprecated functions that should not be used. This header is
included in <filename>ldap.h</filename>.</para></entry>
</row>
<row>
<entry>
<para><filename>ldap-extension.h</filename></para></entry>
<entry>
<para>Contains functions, structures, and defines that extend the standard
LDAP C API specification. This header is included in <filename>ldap.h</filename>.
</para></entry>
</row>
<row>
<entry>
<para><filename>ldap-platform.h</filename></para></entry>
<entry>
<para>A private header file that contains platform-specific definitions, which
allow abstraction from the underlying system.</para></entry>
</row>
<row>
<entry>
<para><filename>ldap-standard.h</filename></para></entry>
<entry>
<para>Contains the standard LDAP functions, structures, and defines. This
header is included in <filename>ldap.h</filename>.</para></entry>
</row>
<row>
<entry>
<para><filename>ldap-to-be-deprecated.h</filename></para></entry>
<entry>
<para>Contains functions, structures, and defines that might be deprecated
in future releases. This header is included in <filename>ldap.h</filename>.</para>
</entry>
</row>
<row>
<entry>
<para><filename>ldap.h</filename></para></entry>
<entry>
<para>This base header contains LDAP functions, structures, and defines to
mirror the latest LDAP C API specifications.</para>
<itemizedlist>
<para>This header also includes the following header files:</para>
<listitem><para><filename>ldap-deprecated.h</filename></para></listitem>
<listitem><para><filename>ldap-extension.h</filename></para></listitem>
<listitem><para><filename>ldap-standard.h</filename></para></listitem>
<listitem><para><filename>ldap-to-be-deprecated.h</filename></para></listitem>
</itemizedlist>
<para>For details, see <olink targetptr="bdaay">ldap.h Header File</olink>.</para>
</entry>
</row>
<row>
<entry>
<para><filename>ldap_ssl.h</filename></para></entry>
<entry colsep="0">
<para>Contains prototypes for LDAP over SSL functions, structures, and defines.
For details, see <olink targetptr="bdaba">ldap_ssl.h Header File</olink></para>
</entry>
</row>
<row>
<entry>
<para><filename>ldappr.h</filename></para></entry>
<entry>
<para>Contains prototypes for the functions, structures, and defines that
are contained in the Netscape Portable Runtime (NSPR) API. For details see<olink targetptr="bdabb">ldappr.h Header File</olink></para></entry>
</row>
<row>
<entry>
<para><filename>srchpref.h</filename></para></entry>
<entry>
<para>A header file related to the search preferences (<filename>ldapsearchprefs.conf
</filename> ).</para></entry>
</row>
</tbody>
</tgroup>
</table>
<sect3 id="bdaay"><title><filename>ldap.h</filename> Header File</title>
<para><indexterm>
<primary><filename>ldap.h</filename> header file</primary>
<secondary>including</secondary>
</indexterm>To make use of the &DirectorySDKForC; functions, include the <filename>
ldap.h</filename> header file in your C source files as shown in this line
of code:</para>
<programlisting>#include "ldap.h"</programlisting>
<itemizedlist>
<para>By including this file, you also include the following header files:</para>
<listitem><para><filename>ldap-deprecated.h</filename></para></listitem>
<listitem><para><filename>ldap-extension.h</filename></para></listitem>
<listitem><para><filename>ldap-standard.h</filename></para></listitem>
<listitem><para><filename>ldap-platform.h</filename></para></listitem>
<listitem><para><filename>ldap-to-be-deprecated.h</filename></para></listitem>
</itemizedlist>
</sect3>
<sect3 id="bdaaz"><title><filename>lber.h</filename> Header File</title>
<indexterm>
<primary><filename>lber.h</filename> header file</primary>
<secondary>including</secondary>
</indexterm>
<para><filename>lber.h</filename> is included in <filename>ldap-standard.h</filename>.
You do not need to include the header explicitly. Basic Encoding Rules (BER)
is a simple tag-value scheme to encode requests and decode results.</para>
</sect3>
<sect3 id="bdaba"><title><filename>ldap_ssl.h</filename> Header File</title>
<para><indexterm>
<primary><filename>ldap_ssl.h</filename> header file</primary>
<secondary>including</secondary>
</indexterm>If you are calling LDAP over SSL functions, you also need to include
the <filename>ldap_ssl.h</filename> header file, as follows:</para>
<programlisting>#include "ldap_ssl.h"</programlisting>
</sect3>
<sect3 id="bdabb"><title><filename>ldappr.h</filename> Header File</title>
<indexterm>
<primary><filename>ldappr.h</filename> header file</primary>
<secondary>including</secondary>
</indexterm>
<para>To make use of the Netscape Portable Runtime (NSPR) API with your LDAP
applications, you must include the <filename>ldappr.h</filename> file. The
NSPR is a set of platform-neutral APIs that provides system functions such
as threads, thread synchronization, I/O, interval timing, and atomic operations.
This header file contains prototypes for functions that tie the LDAP libraries
to NSPR. You include the header file as follows:</para>
<programlisting>#include "ldappr.h"</programlisting>
<para>For more information about NSPR, see the <literal>ldappr.h</literal> header
file and the Netscape Portable Runtime project page at <ulink
url="
http://www.mozilla.org/projects/nspr/" type="text_url">http://www.mozilla.org/projects/nspr/
</ulink>.</para></sect3>
</sect2>
<sect2 id="bdabc"><title>Miscellaneous Files</title>
<indexterm>
<primary><filename>ldapfilter.conf</filename>sample file</primary>
</indexterm><indexterm>
<primary><filename>ldapfriendly</filename>sample file</primary>
</indexterm><indexterm>
<primary><filename>ldapsearchprefs.conf</filename>sample file</primary>
</indexterm><indexterm>
<primary><filename>ldaptemplates.conf</filename>sample file</primary>
</indexterm><indexterm>
<primary>C SDK</primary>
<secondary>sample files</secondary>
</indexterm>
<para>&DirectorySDKForC; includes the sample files described in the following
table. Sample files can be retrieved when using certain APIs. Sample files
are located in the <filename>etc/</filename> directory. All locations are
relative to the directory where the software is installed, which depends on
your operating system.</para>
<table frame="topbot" pgwide="1" id="csdk-sample-config"><title>Sample Configuration
Files</title>
<tgroup cols="2"><colspec colnum="1" colwidth="24.27*"><colspec colnum="2"
colwidth="75.73*">
<thead>
<row>
<entry>
<para>File Name</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><filename>ldapfilter.conf</filename></para></entry>
<entry>
<para>This filter configuration file can be used in context with <function>ldap_init_getfilter
</function>.</para></entry>
</row>
<row>
<entry>
<para><filename>ldapfriendly</filename></para></entry>
<entry>
<para>This file is used to map the two&mdash;letter country codes to their
full names by <function>ldap_friendly_name</function>.</para></entry>
</row>
<row>
<entry>
<para><filename>ldapsearchprefs.conf</filename></para></entry>
<entry>
<para>This configuration file was used in context with a deprecated function.</para>
</entry>
</row>
<row>
<entry>
<para><filename>ldaptemplates.conf</filename></para></entry>
<entry>
<para>This configuration file was used in context with a deprecated function.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdabd"><title>&DirectorySDKForC; Libraries</title>
<indexterm>
<primary>C SDK</primary>
<secondary>libraries</secondary>
</indexterm><indexterm>
<primary>libraries</primary>
<secondary>C SDK</secondary>
</indexterm>
<para>&DirectorySDKForC; includes several different libraries. A library
is a set of ready-made functions that are linked into a program. &DirectorySDKForC; uses <firstterm>
shared</firstterm> libraries. Shared libraries are dynamically loaded into
memory when needed, reducing the size of the executable.</para>
<sect3 id="bdabe"><title>Library Naming Conventions</title>
<para>Libraries on different systems have different naming conventions. The
following table shows the&DirectorySDKForC; naming conventions.</para>
<table frame="topbot" pgwide="1" id="csdk-naming-conventions"><title>Library
Naming Convention by Operating System</title>
<tgroup cols="3">
<?PubTbl tgroup dispwid="712.00px">
<colspec colnum="1" colwidth="25.72*"><colspec colnum="2" colwidth="28.14*">
<colspec colnum="3" colwidth="46.13*">
<thead>
<row>
<entry>
<para>Operating System</para></entry>
<entry>
<para>Static Library Name</para></entry>
<entry>
<para>Shared Library Name</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Solaris and Red Hat systems</para></entry>
<entry>
<para><filename>lib<replaceable>libraryname</replaceable>.a</filename></para>
</entry>
<entry>
<para><filename>lib<replaceable>libraryname</replaceable>.so.<replaceable>versionnumber
</replaceable></filename></para></entry>
</row>
<row>
<entry>
<para>HP-UX systems</para></entry>
<entry>
<para><filename>lib<replaceable>libraryname</replaceable>.a</filename></para>
</entry>
<entry>
<para><filename>lib<replaceable>libraryname</replaceable>.sl</filename></para>
</entry>
</row>
<row>
<entry>
<para>Windows systems</para></entry>
<entry>
<para><filename>ns<replaceable>libraryname</replaceable>.lib</filename></para>
</entry>
<entry>
<para><filename>ns<replaceable>libraryname</replaceable>.dll</filename></para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>On <trademark class="registered">UNIX</trademark> systems, the shared
library file name can be fully qualified by prefixing path information.</para>
</sect3>
<sect3 id="bdabf"><title>Installed Shared Libraries</title>
<para>The following table describes the installed libraries that are in the <filename>
lib/</filename> directory. All locations are relative to the directory where
the software is installed, which depends on your operating system.</para>
<table frame="topbot" pgwide="1" id="csdk-shared-libs"><title>Shared Libraries</title>
<tgroup cols="3"><colspec colnum="1" colwidth="17.02*"><colspec colnum="2"
colwidth="18.77*"><colspec colnum="3" colwidth="64.22*">
<thead>
<row>
<entry>
<para>UNIX Library</para></entry>
<entry>
<para>Windows Library</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><filename>libldap60.so</filename></para></entry>
<entry>
<para><filename>nsldap32v60.dll</filename></para></entry>
<entry>
<para>LDAP library.</para></entry>
</row>
<row>
<entry>
<para><literal>libprldap60.so</literal></para></entry>
<entry>
<para><literal>nsldappr32v60.dll</literal></para></entry>
<entry>
<para>LDAP library built with NSPR.</para>
<para>This library requires the <filename>libnspr4.so</filename> library in
the <filename>lib-private/</filename> directory.</para></entry>
</row>
<row>
<entry>
<para><literal>libssldap60.so</literal></para></entry>
<entry>
<para><literal>nsldapssl32v60.dll</literal></para></entry>
<entry>
<para>LDAP library that is built with support for the Secure Sockets Layer
protocol.</para>
<para>This library depends on the <filename>libnss3.so</filename> and <filename>libnspr4.so
</filename> libraries in the <filename>lib-private/</filename> directory.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
<sect3 id="bdabg"><title>&DirectorySDKForC; Dependencies</title>
<itemizedlist>
<para>&DirectorySDKForC; resolves dependencies for the following APIs at
run&mdash;time:</para>
<listitem><para>Netscape Portable Runtime (NSPR) provides core cross-platform
functions.</para></listitem>
<listitem><para>Netscape Security Services (NSS) provides encryption, cryptographic,
Secure Sockets Layer (SSL), and Public Key Infrastructure (PKI) support.</para>
</listitem>
<listitem><para>Simple Authentication and Security Layer (SASL) provides support
for applications that require SASL.</para></listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2 id="bdabh"><title>LDAP Tools</title>
<indexterm>
<primary>LDAP tools</primary>
</indexterm>
<para>&DirectorySDKForC; includes several utilities to help you work with
LDAP data sets. These utilities are installed in the <filename>tools/</filename> directory.
For details on each tool described in the following table, see the corresponding
man pages. A list of options can be retrieved by typing the tool name at the
command line.</para>
<table frame="topbot" pgwide="1" id="csdk-tools"><title>&DirectorySDKForC; LDAP
Tools</title>
<tgroup cols="2"><colspec colnum="1" colwidth="13.45*"><colspec colnum="2"
colwidth="86.55*">
<thead>
<row>
<entry>
<para>Command</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><command>ldapcmp</command></para></entry>
<entry>
<para>Compares the contents of a single LDAP entry or subtree in two directories.
</para></entry>
</row>
<row>
<entry>
<para><command>ldapcompare</command></para></entry>
<entry>
<para>Compares an attribute value against the contents of a given LDAP entry.</para>
</entry>
</row>
<row>
<entry>
<para><command>ldapdelete</command></para></entry>
<entry>
<para>Deletes existing LDAP entries.</para></entry>
</row>
<row>
<entry>
<para><command>ldapmodify</command></para></entry>
<entry>
<para>Edits the contents of an LDAP directory, either by adding new entries
or modifying existing ones.</para></entry>
</row>
<row>
<entry>
<para><command>ldappasswd</command></para></entry>
<entry>
<para>Changes user passwords on LDAP entries.</para></entry>
</row>
<row>
<entry>
<para><command>ldapsearch</command></para></entry>
<entry>
<para>Issues search requests to an LDAP directory, then displays the result
as LDAP Data Interchange Format (LDIF) text.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
</sect1>
<sect1 id="bdabi"><title>Compiling Applications with Directory SDK for C</title>
<indexterm>
<primary>C SDK</primary>
<secondary>compiling applications</secondary>
</indexterm>
<para>When compiling applications, you must include the header files and link
to the libraries required. Information about including the header files is
in <olink targetptr="bdaax">Directory SDK for C Header Files</olink>. Linking
to shared libraries is covered in this section. &DirectorySDKForC; is qualified
to work with C compilers.</para>
<caution><para>&DirectorySDKForC; is not guaranteed to work with C++ compilers.
</para></caution>
<sect2 id="bdabj"><title>Compiling on UNIX Platforms</title>
<para>When compiling clients on UNIX platforms, specify link options correctly
to link the application to the appropriate shared libraries. See the <filename>Makefile
</filename> in the <filename>examples/</filename> directory for details on
compiling your applications on UNIX platforms.</para></sect2>
<sect2 id="bdabk"><title>Compiling on Windows Systems With &DirectorySDKForC;</title>
<itemizedlist>
<para>A Windows application can use either a command-line interface or a graphical
user interface (GUI). Windows systems refer to a console application. In a
console application, all user interaction happens through the command shell
interface, with a <structname>FILE</structname> pointer as found in UNIX systems.
Given this difference, make sure that you define the following:</para>
<listitem><para><literal>_CONSOLE</literal> if you are writing a console application
</para></listitem>
<listitem><para><literal>_WINDOWS</literal> if you are writing a standard
Windows GUI application</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="bdabo"><title>Linking Dependencies</title>
<indexterm>
<primary>libraries</primary>
<secondary>runtime</secondary>
</indexterm>
<para>When you run LDAP clients, you must ensure that the operating system
can find the shared libraries that support the functions called by your application.
Generally, these files are referred to as <emphasis>runtime</emphasis> libraries.
Any of the following options ensure that the operating system can find the
shared libraries.</para>
<itemizedlist>
<listitem><para>Make sure that the shared library file, such as <filename>libldap60.so
</filename>, is in a location specified by environment variables.</para>
</listitem>
<listitem><para>On some platforms, clients can be complied with flags that
let you set the runtime path to load libraries as an environment variable.</para>
<itemizedlist>
<listitem><para>On <trademark>Solaris</trademark> and Red Hat systems, you
can use the <envar>LD_LIBRARY_PATH</envar> environment variable if you use
the <literal>-Wl,+s+b</literal> flag when compiling and linking.</para>
</listitem>
<listitem><para>On HP-UX system, use the <envar>SHLIB_PATH</envar> environment
variable.</para></listitem>
<listitem>
<orderedlist>
<para>On Windows systems, copy all dynamic link libraries (DLLs) needed for
your application to a directory where your client can find the libraries.
Other software might install a different version of the DLLs in the Windows <filename>
system32\</filename> directory. Make sure that your client finds the DLLs
included with &DirectorySDKForC; before your client finds the version in
the <filename>system32\</filename> directory. At runtime, your client searches
for the DLL in the following locations in the order shown:</para>
<listitem><para>The directory from which the application loaded</para>
</listitem>
<listitem><para>The current directory</para></listitem>
<listitem><para>The Windows system directory, typically <filename>winnt\system32\
</filename></para><para>To avoid potential conflicts, do not copy the DLL
to this directory</para></listitem>
<listitem><para>The directories listed in the <envar>PATH</envar> environment
variable</para></listitem>
</orderedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem><para>Use a link flag that specifies the path where the executable
can find the library. For example, on Solaris systems, you can use the <literal>-R
</literal> flag to specify the path where the executable can find the library.</para>
<para>See the <filename>Makefile</filename> in the <filename>examples/</filename> directory
for examples of additional settings for compiling and linking your LDAP client.
Different platforms might require different sets of define statements.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="bdabp"><title>Sample Programs for Directory SDK for C</title>
<indexterm>
<primary>C SDK</primary>
<secondary>sample programs</secondary>
</indexterm><indexterm>
<primary>example programs</primary>
<secondary>C SDK</secondary>
</indexterm>
<para>&DirectorySDKForC; includes several examples that demonstrate the
use of the functions that the SDK provides. The examples are located in the <filename>
examples/</filename> directory. The example code is designed to run against
the LDAP v3 compliant &cnDirectoryServer;. Furthermore, the example code is
designed to work with  sample data that has been properly loaded. For details
on the source files, refer to the <filename>README</filename> in the <filename>examples/
</filename> directory.</para>
<para>The samples use synchronous LDAP calls and their asynchronous counterparts.
Because synchronous LDAP calls are more straightforward than their asynchronous
counterparts, look at the synchronous examples first.</para>
<sect2 id="bdabq"><title>Synchronous Examples</title>
<indexterm>
<primary>C SDK</primary>
<secondary>synchronous examples</secondary>
</indexterm><indexterm>
<primary>example programs</primary>
<secondary>C SDK</secondary>
<tertiary>synchronous</tertiary>
</indexterm>
<para>The synchronous calls block the calling process until all results have
been returned. As these programs usually rely on event loops, the programs
are not appropriate for use with clients that implement a GUI in a single-threaded
environment. However, these sample programs do work with command-line clients
and CGI programs.</para>
<table frame="topbot" pgwide="1" id="csdk-sync-examples"><title>Synchronous
Example Programs</title>
<tgroup cols="2"><colspec colnum="1" colwidth="18.17*"><colspec colnum="2"
colwidth="81.83*">
<thead>
<row>
<entry>
<para>Example Source</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><filename>authzid.c</filename></para></entry>
<entry>
<para>Shows how to use the authorization ID control, which allows you to get
the authorization ID for an LDAP operation.</para></entry>
</row>
<row>
<entry>
<para><filename>compare.c</filename></para></entry>
<entry>
<para>Shows how to use <function>ldap_compare_s</function>, which allows you
to test if a particular value is contained in an attribute of an entry.</para>
</entry>
</row>
<row>
<entry>
<para><filename>crtfilt.c</filename></para></entry>
<entry>
<para>Shows how to use the <function>ldap_create_filter</function> function
to generate LDAP filters.</para></entry>
</row>
<row>
<entry>
<para><filename>csearch.c</filename></para></entry>
<entry>
<para>Like <filename>search.c</filename>, but enables an in-memory cache.</para>
</entry>
</row>
<row>
<entry>
<para><filename>effright.c</filename></para></entry>
<entry>
<para>Shows how to use the get effective rights control, which allows you
to determine access rights to entries and their attributes.</para></entry>
</row>
<row>
<entry>
<para><filename>getattrs.c</filename></para></entry>
<entry>
<para>Retrieves specific attributes from an entry.</para></entry>
</row>
<row>
<entry>
<para><filename>getfilt.c</filename></para></entry>
<entry>
<para>Shows how to use the <function>ldap_getfilter*</function> family of
functions, which generate LDAP filters that are based on an arbitrary search
string provided by a user.</para></entry>
</row>
<row>
<entry>
<para><filename>modattrs.c</filename></para></entry>
<entry>
<para>Shows how to use <function>ldap_modify_s</function> to replace and add
to values in an attribute.</para></entry>
</row>
<row>
<entry>
<para><filename>modrdn.c</filename></para></entry>
<entry>
<para>Shows how to use <function>ldap_modrdn2_s</function> to change the relative
distinguished name (RDN) of an entry.</para></entry>
</row>
<row>
<entry>
<para><filename>pwdextop.c</filename></para></entry>
<entry>
<para>Shows how to use the LDAP password modify extended operation to change
a password.</para></entry>
</row>
<row>
<entry>
<para><filename>pwdpolicy.c</filename></para></entry>
<entry>
<para>Shows how to use the password policy control. This control allows you
to retrieve information about the password policy that applies to the user
binding to the directory.</para></entry>
</row>
<row>
<entry>
<para><filename>rdentry.c</filename></para></entry>
<entry>
<para>Shows how to use <function>ldap_search_s</function> to retrieve a particular
entry from the directory.</para></entry>
</row>
<row>
<entry>
<para><filename>realattr.c</filename></para></entry>
<entry>
<para>Shows how to use the control to retrieve only real attributes during
a search.</para></entry>
</row>
<row>
<entry>
<para><filename>search.c</filename></para></entry>
<entry>
<para>Shows how to use <function>ldap_search_s</function> to search for all
entries that have an attribute value that exactly matches what you search
for. </para></entry>
</row>
<row>
<entry>
<para><filename>srvrsort.c</filename></para></entry>
<entry>
<para>Shows how to use server-side sorting in conjunction with the <function>ldap_search_ext_s
</function> function.</para></entry>
</row>
<row>
<entry>
<para><filename>ssearch.c</filename></para></entry>
<entry>
<para>Like <filename>ssnoauth.c</filename>, but includes certificate-based
authentication.</para></entry>
</row>
<row>
<entry>
<para><filename>ssnoauth.c</filename></para></entry>
<entry>
<para>Like <filename>search.c</filename>, but the search is done over an SSL-protected
TCP connection.</para></entry>
</row>
<row>
<entry>
<para><filename>starttls.c</filename></para></entry>
<entry>
<para>Shows how to use the Start TLS extended operation.</para></entry>
</row>
<row>
<entry>
<para><filename>userstatus.c</filename></para></entry>
<entry>
<para>Shows how to use the account status control to retrieve information
about the account of the user binding to the directory.</para></entry>
</row>
<row>
<entry>
<para><filename>virtattr.c</filename></para></entry>
<entry>
<para>Shows how to use the control to retrieve only virtual attributes during
a search.</para></entry>
</row>
<row>
<entry>
<para><filename>whoami.c</filename></para></entry>
<entry>
<para>Shows how to use the Who am I? extended operation to retrieve the authorization
ID.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="bdabr"><title>Asynchronous Examples</title>
<indexterm>
<primary>C SDK</primary>
<secondary>asynchronous examples</secondary>
</indexterm><indexterm>
<primary>example programs</primary>
<secondary>C SDK</secondary>
<tertiary>asynchronous programs</tertiary>
</indexterm>
<para>These examples use the asynchronous LDAP calls. You begin an operation.
You then periodically poll to see if any results have been returned.</para>
<table frame="topbot" pgwide="1" id="csdk-async-examples"><title>Asynchronous
Example Programs</title>
<tgroup cols="2"><colspec colnum="1" colwidth="16.64*"><colspec colnum="2"
colwidth="83.36*">
<thead>
<row>
<entry>
<para>Example Source</para></entry>
<entry>
<para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><filename>add.c</filename></para></entry>
<entry>
<para>Adds an entry to the directory.</para></entry>
</row>
<row>
<entry>
<para><filename>asearch.c</filename></para></entry>
<entry>
<para>Initiates a search for entries, printing the results on arrival.</para>
</entry>
</row>
<row>
<entry>
<para><filename>del.c</filename></para></entry>
<entry>
<para>Deletes an entry from the directory.</para></entry>
</row>
<row>
<entry>
<para><filename>nsprio.c</filename></para></entry>
<entry>
<para>Like <literal>asearch.</literal> but uses the PerLDAP routines to incorporate
the Netscape Portable Runtime (NSPR) API.</para></entry>
</row>
<row>
<entry>
<para><filename>ppolicy.c</filename></para></entry>
<entry>
<para>Attempts to bind to the directory and reports back any password expiration
information received. This program demonstrates how clients can process password
policy information.</para></entry>
</row>
<row>
<entry>
<para><filename>psearch.c</filename></para></entry>
<entry>
<para>Shows how to use Persistent Search, an LDAP v3 extension, to monitor
a directory for changes.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
</sect1>
</chapter>
