376 lines
16 KiB
Plaintext
376 lines
16 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.
|
|
|
|
-->
|
|
<preface id="preface"><title>Preface</title>
|
|
<highlights>&abstract;
|
|
</highlights>
|
|
<sect1 id="who-should-read"><title>Who Should Use This Book</title>
|
|
<para>This guide is intended for developers creating directory client applications.
|
|
</para>
|
|
<itemizedlist>
|
|
<para>Before using this guide, you must be familiar with the following:</para>
|
|
<listitem><para>&cnDirectoryServer; functionality</para></listitem>
|
|
<listitem><para>Developing programs in the C programming
|
|
language</para></listitem>
|
|
<listitem><para>Specifications for LDAP and related protocols, such as DSML
|
|
v2</para></listitem>
|
|
<listitem><para>Internet and World Wide Web technologies</para></listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
<sect1 id="before-you-read"><title>Before You Read This Book</title>
|
|
<para>Before developing directory client applications, install &DirectorySDKForJava;.
|
|
</para>
|
|
<!-- TODO: Need an XREF to installation instructions -->
|
|
</sect1>
|
|
<sect1 id="reading-for-developers"><title>Additional Recommended Reading</title>
|
|
<itemizedlist>
|
|
<para>Directory client application developers might benefit from reading the
|
|
following books:</para>
|
|
<listitem><para><citetitle>LDAP Programming with Java</citetitle> by Weltman
|
|
and Dabhura (ISBN 0-201-65758-96)</para></listitem>
|
|
<listitem><para><citetitle>LDAP Programming, Management and Integration</citetitle> by
|
|
Donley (ISBN 1930110405)</para></listitem>
|
|
<listitem><para><citetitle>LDAP: Programming Directory-Enabled Applications
|
|
with Lightweight Directory Access Protocol</citetitle> by Howes and Smith
|
|
(ISBN 1-57870-000-00)</para></listitem>
|
|
<listitem><para><citetitle>Understanding and Deploying LDAP Directory Services</citetitle> by
|
|
Howes, et al. (ISBN 1-57870-070-10)</para></listitem>
|
|
</itemizedlist>
|
|
<itemizedlist>
|
|
<para>In addition, keep bookmarks to the following IETF documents:</para>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2251.txt" type="text_url">
|
|
RFC 2251</ulink>, <citetitle>Lightweight Directory Access Protocol (v3)</citetitle></para>
|
|
</listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2252.txt" type="text_url">
|
|
RFC 2252</ulink>, <citetitle>Lightweight Directory Access Protocol (v3): Attribute
|
|
Syntax Definitions</citetitle></para></listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2253.txt" type="text_url">
|
|
RFC 2253</ulink>, <citetitle>Lightweight Directory Access Protocol (v3): UTF-8
|
|
String Representation of Distinguished Names</citetitle></para></listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2254.txt" type="text_url">
|
|
RFC 2254</ulink>, <citetitle>The String Representation of LDAP Search Filters</citetitle></para>
|
|
</listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2255.txt" type="text_url">
|
|
RFC 2255</ulink>, <citetitle>The LDAP URL Format</citetitle></para></listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2256.txt" type="text_url">
|
|
RFC 2256</ulink>, <citetitle>A Summary of the X.500(96) User Schema for use
|
|
with LDAPv3</citetitle></para></listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2829.txt" type="text_url">
|
|
RFC 2829</ulink>, <citetitle>Authentication Methods for LDAP</citetitle></para>
|
|
</listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2830.txt" type="text_url">
|
|
RFC 2830</ulink>, <citetitle>Lightweight Directory Access Protocol (v3): Extension
|
|
for Transport Layer Security</citetitle></para></listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc2849.txt" type="text_url">
|
|
RFC 2849</ulink>, <citetitle>The LDAP Data Interchange Format (LDIF) - Technical
|
|
Specification</citetitle></para></listitem>
|
|
<listitem><para><ulink url="http://www.ietf.org/rfc/rfc3377.txt" type="text_url">
|
|
RFC 3377</ulink>, <citetitle>Lightweight Directory Access Protocol (v3): Technical
|
|
Specification</citetitle></para></listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
<sect1 id="organization"><title>How This Book Is Organized</title>
|
|
<itemizedlist>
|
|
<para>This guide includes the following chapters.</para>
|
|
<listitem><para><olink targetptr="understanding-ldap">Chapter 1, Understanding
|
|
LDAP</olink> describes LDAP and directory concepts.</para></listitem>
|
|
<listitem><para><olink targetptr="best-practices-choose">Chapter 2, Choosing
|
|
a Client SDK</olink> covers what to consider when choosing a software development
|
|
kit for building directory client applications.</para></listitem>
|
|
<listitem><para><olink targetptr="best-practices-overview">Chapter 3,
|
|
Best Practices for Writing Client Applications</olink> reviews what and what
|
|
not to do when building directory client applications.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-using">Chapter 4, About Directory
|
|
SDK for C</olink> describes what &DirectorySDKForC; offers you as a directory
|
|
client developer.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-quickstart">Chapter 5, Getting
|
|
Started With Directory SDK for C</olink> gets you started using &DirectorySDKForC;.
|
|
</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-whatsnew">Chapter 6, What's New
|
|
In Directory SDK for C</olink> presents new features, and changes from previous
|
|
versions of &DirectorySDKForC;.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-client">Chapter 7, Writing an
|
|
LDAP Client With Directory SDK for C</olink> covers the basics of writing
|
|
a directory client application.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-api">Chapter 8, Using the LDAP
|
|
C API</olink> shows how to write an application with &DirectorySDKForC;.</para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="csdk-searching">Chapter 9, Searching
|
|
the Directory With Directory SDK for C</olink> shows how to write client application
|
|
code for searching a directory.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-filter">Chapter 10, Using Filter
|
|
Configuration Files With Directory SDK for C</olink> shows how to write code
|
|
to search a directory using filter configuration files.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-write">Chapter 11, Adding, Updating,
|
|
and Deleting Entries With Directory SDK for C</olink> shows how to write client
|
|
application code for changing directory entries.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-compare">Chapter 12, Comparing
|
|
Attribute Values With Directory SDK for C</olink> shows how to compare attribute
|
|
values in a directory with known values.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-urls">Chapter 13, LDAP URLs With
|
|
Directory SDK for C</olink> shows how to handle LDAP URLs.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-server-info">Chapter 14, Getting
|
|
Server Information With Directory SDK for C</olink> shows how to retrieve
|
|
information about the directory and directory service.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-ssl">Chapter 15, SSL Connections
|
|
With Directory SDK for C</olink> shows how to write client application code
|
|
that connects to the directory over SSL.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-controls">Chapter 16, LDAP Controls
|
|
With Directory SDK for C</olink> shows how to handle supported LDAP controls.</para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="csdk-sasl">Chapter 17, SASL Authentication
|
|
With Directory SDK for C</olink> shows how to connect to the directory by
|
|
using SASL.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-extop">Chapter 18, Extended Operations
|
|
With Directory SDK for C</olink> shows how to write client application code
|
|
for handling LDAP v3 extended operations.</para></listitem>
|
|
<listitem><para><olink targetptr="csdk-multithread">Chapter 19, Writing
|
|
Multithreaded Clients With Directory SDK for C</olink> shows how to write
|
|
multithreaded client application code.</para></listitem>
|
|
<listitem><para><olink targetptr="bdajr">Chapter 20, Directory SDK for C Data Type Reference</olink> covers &DirectorySDKForC; data types</para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="bdane">Chapter 21, Directory SDK for C Function Reference</olink> covers &DirectorySDKForC; functions</para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="bdaxx">Chapter 22, Directory SDK for C Result Codes</olink> covers &DirectorySDKForC; function result codes</para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="share-alike">Appendix A, Creative Commons Attribution-ShareAlike 2.5</olink> provides the full text of the license governing this guide</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
<sect1 id="related-reading"><title>Related Reading</title>
|
|
<para><indexterm>
|
|
<primary>SLAMD Distributed Load Generation Engine</primary>
|
|
</indexterm>The SLAMD Distributed Load Generation Engine (SLAMD) is a <trademark>
|
|
Java</trademark> application that is designed to stress test and analyze the
|
|
performance of network-based applications. It was originally developed by
|
|
Sun Microsystems, Inc. to benchmark and analyze the performance of LDAP directory
|
|
servers. SLAMD is available as an open source application under the Sun Public
|
|
License, an OSI-approved open source license. To obtain information about
|
|
SLAMD, go to <ulink url="http://www.slamd.com/" type="url"></ulink>. SLAMD
|
|
is also available as a java.net project. See <ulink
|
|
url="https://slamd.dev.java.net/" type="url"></ulink>.</para>
|
|
<para><indexterm>
|
|
<primary>Java Naming and Directory Interface</primary>
|
|
</indexterm>Java Naming and Directory Interface (JNDI) technology supports
|
|
accessing the Directory Server using LDAP and DSML v2 from Java applications.
|
|
For information about JNDI, see <ulink url="http://java.sun.com/products/jndi/"
|
|
type="url"></ulink>. The <citetitle>JNDI Tutorial</citetitle> contains detailed
|
|
descriptions and examples of how to use JNDI. This tutorial is at <ulink
|
|
url="http://java.sun.com/products/jndi/tutorial/" type="url"></ulink>.</para>
|
|
</sect1>
|
|
<sect1 id="FWBKX"><title>Typographic Conventions</title>
|
|
<para>The following table describes the typographic changes that are used
|
|
in this book.</para>
|
|
<table frame="topbot" id="FWBTE"><title>Typographic Conventions</title>
|
|
<tgroup cols="3" colsep="0" rowsep="0"><colspec colwidth="15*"><colspec
|
|
colwidth="40*"><colspec colwidth="45*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry align="left">
|
|
<para>Typeface</para></entry>
|
|
<entry align="left">
|
|
<para>Meaning</para></entry>
|
|
<entry align="left">
|
|
<para>Example</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><literal>AaBbCc123</literal></para></entry>
|
|
<entry>
|
|
<para>The names of commands, files, and directories, and onscreen computer
|
|
output</para></entry>
|
|
<entry>
|
|
<para>Edit your <filename>.login</filename> file.</para>
|
|
<para>Use <command>ls <option>a</option></command> to list all files.</para>
|
|
<para><computeroutput>machine_name% you have mail.</computeroutput></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><userinput>AaBbCc123</userinput></para></entry>
|
|
<entry>
|
|
<para>What you type, contrasted with onscreen computer output</para></entry>
|
|
<entry>
|
|
<para><computeroutput>machine_name%</computeroutput> <userinput>su</userinput></para>
|
|
<para><computeroutput>Password:</computeroutput></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><replaceable>AaBbCc123</replaceable></para></entry>
|
|
<entry>
|
|
<para>A placeholder to be replaced with a real name or value</para></entry>
|
|
<entry>
|
|
<para>The command to remove a file is <command>rm</command> <replaceable>filename
|
|
</replaceable>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><emphasis>AaBbCc123</emphasis></para></entry>
|
|
<entry>
|
|
<para>Book titles, new terms, and terms to be emphasized (note that some emphasized
|
|
items appear bold online)</para></entry>
|
|
<entry>
|
|
<para>Read Chapter 6 in the <citetitle>User's Guide</citetitle>.</para>
|
|
<para>A <emphasis>cache</emphasis> is a copy that is stored locally.</para>
|
|
<para>Do <emphasis>not</emphasis> save the file.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect1>
|
|
<sect1 id="FWBMK"><title>Shell Prompts in Command Examples</title>
|
|
<para>The following table shows default system prompts and superuser prompts.</para>
|
|
<table frame="topbot" id="GCTTT"><title>Shell Prompts</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="75*"><colspec
|
|
colwidth="25*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Shell</para></entry>
|
|
<entry>
|
|
<para>Prompt</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para>C shell on UNIX and Linux systems</para></entry>
|
|
<entry>
|
|
<para><literal>machine_name%</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>C shell superuser on UNIX and Linux systems</para></entry>
|
|
<entry>
|
|
<para><literal>machine_name#</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Bourne shell and Korn shell on UNIX and Linux systems</para></entry>
|
|
<entry>
|
|
<para><literal>$</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Bourne shell and Korn shell superuser on UNIX and Linux systems</para>
|
|
</entry>
|
|
<entry>
|
|
<para><literal>#</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Microsoft Windows command line</para></entry>
|
|
<entry>
|
|
<para><literal>C:\</literal></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect1>
|
|
<sect1 id="FQUVC"><title>Symbol Conventions</title>
|
|
<para>The following table explains symbols that might be used in this book.</para>
|
|
<table frame="topbot" id="FQUVR"><title>Symbol Conventions</title>
|
|
<tgroup cols="4" colsep="0" rowsep="0"><colspec colnum="1" colwidth="8*"
|
|
align="center"><colspec colnum="2" colwidth="28*"><colspec colnum="3"
|
|
colwidth="28*"><colspec colnum="4" colwidth="36*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Symbol</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
<entry>
|
|
<para>Example</para></entry>
|
|
<entry>
|
|
<para>Meaning</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><literal>[ ]</literal></para></entry>
|
|
<entry>
|
|
<para>Contains optional arguments and command options.</para></entry>
|
|
<entry>
|
|
<para><literal>ls [-l]</literal></para></entry>
|
|
<entry>
|
|
<para>The <literal>-l</literal> option is not required.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>{ | }</literal></para></entry>
|
|
<entry>
|
|
<para>Contains a set of choices for a required command option.</para></entry>
|
|
<entry>
|
|
<para><literal>-d {y|n}</literal></para></entry>
|
|
<entry>
|
|
<para>The <literal>-d</literal> option requires that you use either the <literal>
|
|
y</literal> argument or the <literal>n</literal> argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>${ }</literal></para></entry>
|
|
<entry>
|
|
<para>Indicates a variable reference.</para></entry>
|
|
<entry>
|
|
<para><literal>${com.sun.javaRoot}</literal></para></entry>
|
|
<entry>
|
|
<para>References the value of the <literal>com.sun.javaRoot</literal> variable.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>-</para></entry>
|
|
<entry>
|
|
<para>Joins simultaneous multiple keystrokes.</para></entry>
|
|
<entry>
|
|
<para>Control-A</para></entry>
|
|
<entry>
|
|
<para>Press the Control key while you press the A key.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>+</para></entry>
|
|
<entry>
|
|
<para>Joins consecutive multiple keystrokes.</para></entry>
|
|
<entry>
|
|
<para>Ctrl+A+N</para></entry>
|
|
<entry>
|
|
<para>Press the Control key, release it, and then press the subsequent keys.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>→</para></entry>
|
|
<entry>
|
|
<para>Indicates menu item selection in a graphical user interface.</para>
|
|
</entry>
|
|
<entry>
|
|
<para>File → New → Templates</para></entry>
|
|
<entry>
|
|
<para>From the File menu, choose New. From the New submenu, choose Templates.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect1>
|
|
</preface>
|
|
|