971 lines
34 KiB
Plaintext
971 lines
34 KiB
Plaintext
<!--
|
|
|
|
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—level and <literal>libc</literal>—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—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—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>
|