<!--

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-whatsnew"><title>What's New In &DirectorySDKForC;</title>
<indexterm>
<primary>upgrading</primary>
<secondary>C SDK</secondary>
</indexterm><highlights>
<para>This chapter compares the current version of &DirectorySDKForC; API
with the previous version.</para>
<itemizedlist>
<para>This chapter covers the following topics:</para>
<listitem><para><olink targetptr="csdk-changed-features">Deprecated and Changed
Directory SDK for C Features</olink></para></listitem>
<listitem><para><olink targetptr="csdk-new-features">New Directory SDK for
C Features</olink></para></listitem>
</itemizedlist>
</highlights><?Pub Caret1>
<sect1 id="csdk-changed-features"><title>Deprecated and Changed &DirectorySDKForC; Features
</title>
<indexterm>
<primary>deprecated features</primary>
<secondary>C SDK</secondary>
</indexterm>
<para>This section covers the following changes and deprecated features in
this release. Where possible, &DirectorySDKForC; provides replacement features
for deprecated features.</para>
<itemizedlist>
<listitem><para><literal>liblber</literal> API</para></listitem>
<listitem><para>File layout</para></listitem>
<listitem><para>IPv6 support</para></listitem>
<listitem><para>NSS and NSPR version updates</para></listitem>
<listitem><para>NSS security tools</para></listitem>
</itemizedlist>
<sect2 id="liblber-changes"><title><filename class="libraryfile">liblber</filename> API 
</title>
<indexterm>
<primary>APIs</primary>
<secondary><filename class="libraryfile">liblber</filename></secondary>
</indexterm><indexterm>
<primary>libraries</primary>
<secondary><filename class="libraryfile">liblber</filename></secondary>
</indexterm>
<para>The Basic Encoding Rules library, <filename class="libraryfile">liblber</filename>,
changed for portability reasons and to comply with <citetitle>The C LDAP Application
Program Interface</citetitle> Internet draft. In particular, according to
section 17.1., <citetitle>BER Data Structures and Types,</citetitle> the following
structures have changed.</para>
<programlisting role="fragment">The following additional integral types are defined for use in manipula-
tion of BER encoded ASN.1 values:

       typedef &lt;impl_tag_t> ber_tag_t;     /* for BER tags */
       typedef &lt;impl_int_t> ber_int_t;     /* for BER ints, enums, and Booleans */
       typedef &lt;impl_unit_t> ber_uint_t;   /* unsigned equivalent of ber_uint_t */
       typedef &lt;impl_slen_t> ber_slen_t;   /* signed equivalent of ber_len_t */

Note that the actual definition for these four integral types is imple-
mentation specific; that is, `&lt;impl_tag_t>', `&lt;impl_int_t>',
`&lt;impl_uint_t>', and `&lt;impl_slen_t>' MUST each be replaced with an
appropriate implementation-specific type.</programlisting>
<para>Programs that do not use the <filename class="libraryfile">liblber</filename> API
directly need not be changed. You can continue to build and use those applications
as before.</para>
<para>If, however, your programs call the <filename class="libraryfile">liblber</filename> API
directly, you must change your application code to reflect the type definitions
in <filename>include/lber.h</filename>. Compilers typically issue type mismatch
warnings when compiling old code that has not been fixed.</para></sect2>
<sect2 id="csdk-file-layout-changes"><title>File Layout</title>
<para>The file layout has changed. All files are unpacked in a base directory
that is named according to the platform and to the operating system of the
binary distribution. The file layout is covered in the section on <olink targetptr="bdaaw">Files Provided With Directory SDK for C</olink>.</para>
</sect2>
<sect2 id="csdk-ipv6-support"><title>IPv6 Support</title>
<para>IPv6 support is provided by means of the NSPR library. Therefore, to
use LDAP over IPv6, use <function>prldap_init</function> instead of <function>ldap_init
</function>.</para></sect2>
<sect2 id="csdk-nss-nspr-versions"><title>NSS and NSPR Version Updates</title>
<para>This version of &DirectorySDKForC; uses NSS 3.11and NSPR 4.6. Both
components are included in binary form for your convenience.</para></sect2>
<sect2 id="nss-security-tools"><title>NSS Security Tools</title>
<para>NSS security tools, used to maintain NSS databases so your application
can do LDAP over SSL, are not delivered with &DirectorySDKForC;.</para>
<para>For access to NSS security tools, refer to the <ulink
url="http://www.mozilla.org/projects/security/pki/nss/tools/" type="text_url">NSS
security tools project</ulink>.</para></sect2>
</sect1>
<sect1 id="csdk-new-features"><title>New &DirectorySDKForC; Features</title>
<indexterm>
<primary>new features</primary>
<secondary>C SDK</secondary>
</indexterm><indexterm>
<primary>C SDK</primary>
<secondary>new features of</secondary>
</indexterm>
<itemizedlist remap="jumplist">
<para>This section describes the features introduced in this release:</para>
<listitem><para><olink targetptr="csdk-ldap-v3-default">LDAP Version 3 Default</olink></para>
</listitem>
<listitem><para><olink targetptr="csdk-more-supported-controls">Supported
Controls</olink></para></listitem>
<listitem><para><olink targetptr="csdk-more-extop-support">Supported Extended
Operations</olink></para></listitem>
<listitem><para><olink targetptr="csdk-more-sample-code">Additional Directory
SDK for C Examples</olink></para></listitem>
</itemizedlist>
<sect2 id="csdk-ldap-v3-default"><title>LDAP Version 3 Default</title>
<para>&DirectorySDKForC; now uses LDAP v3 by default. You can therefore
use LDAP v3 features in your applications even if you do not specifically
set the version to 3.</para></sect2>
<sect2 id="csdk-more-supported-controls"><title>Supported Controls</title>
<para>This version of &DirectorySDKForC; adds support for developing client
applications, including more than 10 LDAP v3 controls. See <olink targetptr="controls-oids">Table 16&ndash;1</olink> for a complete list.</para>
<para>For instructions on using controls supported by &DirectorySDKForC;,
see <olink targetptr="csdk-controls">Chapter&nbsp;16, LDAP Controls With Directory
SDK for C</olink>.</para></sect2>
<sect2 id="csdk-more-extop-support"><title>Supported Extended Operations</title>
<indexterm>
<primary>extended operations</primary>
<secondary>C SDK support of</secondary>
</indexterm>
<para>This version of &DirectorySDKForC; adds support for developing client
applications that use the following extended operations.</para>
<variablelist>
<varlistentry><term>LDAP Password Modify Extended Operation</term>
<listitem><para>The LDAP Password Modify extended operation lets your client
application modify a user password through LDAP. A user can modify his password
even if the password is not stored as an attribute in the directory, the user
is not identified by a DN, or the user does not have an entry in the directory.
The LDAP Password Modify extended operation is defined in <ulink
url="http://www.ietf.org/rfc/rfc3062.txt" type="text_url">RFC 3062</ulink>.</para>
<para>The extended operation has identifier <literal>1.3.6.1.4.1.4203.1.11.1</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>Start TLS Extended Operation</term>
<listitem><para>The Start TLS extended operation lets your client application
connect to a nonsecure port, and then request transport layer security.</para>
<para>The extended operation has identifier <literal>1.3.6.1.4.1.1466.20037</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>Who Am I? Extended Operation</term>
<listitem><para>The &ldquo;Who am I?&rdquo; extended operation lets your client
application determine the authorization identity that the server currently
associates with your client.</para>
<para>The extended operation has identifier <literal>1.3.6.1.4.1.4203.1.11.3</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>For instructions on using extended operations supported by &DirectorySDKForC;,
see <olink targetptr="csdk-extop">Chapter&nbsp;18, Extended Operations With
Directory SDK for C</olink>.</para></sect2>
<sect2 id="csdk-more-sample-code"><title>Additional &DirectorySDKForC; Examples
</title>
<indexterm>
<primary>example programs</primary>
<secondary>C SDK</secondary>
</indexterm>
<para>More sample code is provided in the <filename>examples/</filename> directory.
The additional samples demonstrate newly supported controls and extended operations.
</para></sect2>
</sect1>
</chapter>
