[Search] [txt|pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00                                                            
Network Working Group                                  Timothy A Howes
INTERNET-DRAFT                                            Mark C Smith
OBSOLETES: RFC 1823                      Netscape Communications Corp.


                 The LDAP Application Program Interface



1.  Status of this Memo

This draft document will be submitted to the RFC Editor as an informa-
tional document. Distribution of this memo is unlimited. Please send
comments to the authors.

This document is an Internet-Draft.  Internet-Drafts are working docu-
ments of the Internet Engineering Task Force (IETF), its areas, and its
working groups.  Note that other groups may also distribute working
documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time.  It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as ``work in progress.''

To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).

2.  Introduction

This document defines a C language application program interface to the
lightweight directory access protocol (LDAP). This document replaces the
previous definition of this API, defined in RFC 1823, updating it to
include support for features found in version 3 of the LDAP protocol, as
well as other changes to support information hiding and thread safety.

The LDAP API is designed to be powerful, yet simple to use. It defines
compatible synchronous and asynchronous interfaces to LDAP to suit a
wide variety of applications. This document gives a brief overview of
the LDAP model, then an overview of how the API is used by an applica-
tion program to obtain LDAP information.  The API calls are described in
detail, followed by an appendix that provides some example code demon-
strating the use of the API. This document provides information to the
Internet community. It does not specify any standard.





Expires 4/97                                                    [Page 1]


LDAP API                                                    October 1996


3.  Overview of the LDAP Model

LDAP is the lightweight directory access protocol, described in [2] and
[7]. It can provide a lightweight frontend to the X.500 directory [1],
or a stand-alone service. In either mode, LDAP is based on a client-
server model in which a client makes a TCP connection to an LDAP server,
over which it sends requests and receives responses. LDAPv3 can also be
used over UDP transport.

The LDAP information model is based on the entry, which contains infor-
mation about some object (e.g., a person).  Entries are composed of
attributes, which have a type and one or more values. Each attribute has
a syntax that determines what kinds of values are allowed in the attri-
bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
values behave during directory operations (e.g., is case significant
during comparisons).

Entries may be organized in a tree structure, usually based on politi-
cal, geographical, and organizational boundaries. Each entry is uniquely
named relative to its sibling entries by its relative distinguished name
(RDN) consisting of one or more distinguished attribute values from the
entry.  At most one value from each attribute may be used in the RDN.
For example, the entry for the person Babs Jensen might be named with
the "Barbara Jensen" value from the commonName attribute.

A globally unique name for an entry, called a distinguished name or DN,
is constructed by concatenating the sequence of RDNs from the entry up
to the root of the tree. For example, if Babs worked for the University
of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
o=University of Michigan, c=US". The DN format used by LDAP is defined
in [4].

Operations are provided to authenticate, search for and retrieve infor-
mation, modify information, and add and delete entries from the tree.
The next sections give an overview of how the API is used and detailed
descriptions of the LDAP API calls that implement all of these func-
tions.

4.  Overview of LDAP API Use

An application generally uses the LDAP API in four simple steps.

-    Initialize an LDAP session with a default LDAP server. The
     ldap_init() call returns a handle to the session, allowing multiple
     connections to be open at once.

-    Authenticate to the LDAP server. The ldap_bind() call and friends
     support a variety of authentication methods.



Expires 4/97                                                    [Page 2]


LDAP API                                                    October 1996


-    Perform some LDAP operations and obtain some results. ldap_search()
     and friends return results which can be parsed by
     ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc.

-    Close the connection. The ldap_unbind() call closes the connection.

Operations can be performed either synchronously or asynchronously.  The
names of the synchronous calls end in _s. For example, a synchronous
search can be completed by calling ldap_search_s(). An asynchronous
search can be initiated by calling ldap_search(). All synchronous rou-
tines return an indication of the outcome of the operation (e.g, the
constant LDAP_SUCCESS or some other error code).  The asynchronous rou-
tines return the message id of the operation initiated. This id can be
used in subsequent calls to ldap_result() to obtain the result(s) of the
operation. An asynchronous operation can be abandoned by calling
ldap_abandon().

Results and errors are returned in an opaque structure called LDAPMes-
sage.  Routines are provided to parse this structure, step through
entries and attributes returned, etc. Routines are also provided to
interpret errors. The next sections describe these routines in more
detail.

5.  Calls for performing LDAP operations

This section describes each LDAP operation API call in detail. All calls
take a "connection handle," a pointer to an LDAP structure containing
per-connection information.  Many routines return results in an LDAPMes-
sage structure. These structures and others are described as needed
below.

5.1.  Initializing an LDAP Session

ldap_init() initializes a session with an LDAP server. The server is not
actually contacted until an operation is performed that requires it,
allowing various options to be set after initialization.

ldap_sslinit() functions the same as ldap_init(), but it also optionally
allows the caller to set up a secure LDAP connection over SSL to the
LDAP server.

        typedef struct ldap LDAP;

        LDAP *ldap_init( char *hostname, int portno );

        LDAP *ldap_sslinit( char *hostname, int portno, int secure );

Use of the following routine is deprecated.



Expires 4/97                                                    [Page 3]


LDAP API                                                    October 1996


        LDAP *ldap_open( char *hostname, int portno );

Parameters are:

hostname Contains a space-separated list of hostnames or dotted strings
         representing the IP address of hosts running an LDAP server to
         connect to. The hosts are tried in the order listed, stopping
         with the first one to which a successful connection is made.
         Note that only ldap_open() attempts to make the connection
         before returning to the caller. Neither ldap_init() or
         ldap_sslinit() connect to the LDAP server.

portno   Contains the TCP or UDP port number to connect to or contact.
         The default LDAP port of 389 can be obtained by supplying the
         constant LDAP_PORT. The default secure (LDAP over SSL) LDAP
         port of 636 can be selected by supplying the constant
         LDAPS_PORT.

secure   Is non-zero to intialize a secure LDAP session over SSL.  If
         secure is zero, regular LDAP session will be initialized.

ldap_init(), ldap_sslinit(), and ldap_open() all return a "session han-
dle," a pointer to an opaque structure that should be passed to subse-
quent calls pertaining to the session. These routines return NULL if the
session cannot be initialized.

One of the ldap_bind calls described below must be completed before
other operations can be performed on the session.

The calling program can set various attributes of the session by calling
the routines described in the next section.

5.2.  LDAP Session Handle Options

The LDAP session handle returned by ldap_init() and friends is a pointer
to an opaque data type representing an LDAP session. Formerly, this data
type was a structure exposed to the caller, and various fields in the
structure could be set to control aspects of the session, such as size
and time limits on searches.

In the interest of insulating callers from inevitable changes to this
structure, these aspects of the session are now accessed through a pair
of accessor functions, described below.

ldap_get_option() is used to access the current value of various
session-wide parameters. ldap_set_option() is used to set the value of
these parameters.




Expires 4/97                                                    [Page 4]


LDAP API                                                    October 1996


           int ldap_get_option( LDAP *ld, int option, void *outvalue );

           int ldap_set_option( LDAP *ld, int option, void *invalue );

Parameters are:

ld     The session handle.

option The name of the option being accessed or set. This parameter
       should be one of the following constants, which have the follow-
       ing meanings.

   LDAP_OPT_DESC
          The underlying socket descriptor corresponding to the default
          LDAP connection.

   LDAP_OPT_DEREF
          Controls how aliases are handled during search. It can have
          one of the following values: LDAP_DEREF_NEVER,
          LDAP_DEREF_SEARCHING, LDAP_DEREF_FINDING, or
          LDAP_DEREF_ALWAYS.  The LDAP_DEREF_SEARCHING value means
          aliases should be dereferenced during the search but not when
          locating the base object of the search. The LDAP_DEREF_FINDING
          value means aliases should be dereferenced when locating the
          base object but not during the search.

   LDAP_OPT_SIZELIMIT
          A limit on the number of entries to return from a search. A
          value of zero means no limit.

   LDAP_OPT_TIMELIMIT
          A limit on the number of seconds to spend on a search. A value
          of zero means no limit

   LDAP_OPT_IO_FN_PTRS
          See the discussion of I/O environments in Section X.

   LDAP_OPT_THREAD_FN_PTRS
          See the discussion of threading environments in Section X.

   LDAP_OPT_REBIND_FN
          See the discussion of ldap_bind() and friends below.

   LDAP_OPT_REBIND_ARG
          See the discussion of ldap_bind() and friends below.

   LDAP_OPT_CACHE_FN_PTRS
          See the discussion of LDAP caching in Section X.



Expires 4/97                                                    [Page 5]


LDAP API                                                    October 1996


   LDAP_OPT_CACHE_STRATEGY
          See the discussion of LDAP caching in Section X.

   LDAP_OPT_CACHE_ENABLE
          See the discussion of LDAP caching in Section X.

   LDAP_OPT_REFERRALS
          This option controls whether the LDAP library automatically
          follows referrals returned by LDAP servers or not. It can be
          set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF.

   LDAP_OPT_SSL
          This option controls whether the default LDAP connection is
          made secure over SSL or not. It can be set to one of the con-
          stants LDAP_OPT_ON or LDAP_OPT_OFF. Note that if
          LDAP_OPT_REFERRALS is set to LDAP_OPT_ON and the LDAP library
          gets a referral to an SSL LDAP server, it will still do SSL if
          possible. This setting has no bearing on connections made when
          chasing referrals.

   LDAP_OPT_RESTART
          This option controls whether LDAP I/O operations should
          automatically be restarted if they abort prematurely. It
          should be set to one of the constants LDAP_OPT_ON or
          LDAP_OPT_OFF. This option is useful if an LDAP I/O operation
          may be interrupted prematurely, for example by a timer going
          off, or other interrrupt.

   LDAP_OPT_VERSION
          This option indicates the version of the default LDAP server.
          It can be one of the constants LDAP_VERSION2 or LDAP_VERSION3.

   LDAP_OPT_SORTKEYS
          This option indicates sort keys that should be sent to the
          server on subsequent search requests. The value of this option
          is a NULL-terminated array of pointers to structures with the
          following definition.

           struct ldapsortkey {
                   char    *sk_attrtype;
                   char    *sk_matchruleoid;
                   int     sk_reverseorder;
           };


outvalue The address of a place to put the value of the option. The
         actual type of this parameter depends on the setting of the
         option parameter.



Expires 4/97                                                    [Page 6]


LDAP API                                                    October 1996


invalue  A pointer to the value the option is to be given. The actual
         type of this parameter depends on the setting of the option
         parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be
         given for options that have on or off settings.

5.3.  Setting Session Parameters

The ldap_session() and ldap_session_s() calls are used to request that
the LDAP server set certain session parameters.  These session parame-
ters are maintained by the server, as opposed to the LDAP * session
parameters described above, which are maintained by the client.

           struct ldapsessctl {
                   char            *sc_type;
                   struct berval   sc_value;
                   int             sc_critical;
           };

           int ldap_session(
                   LDAP                    *ld;
                   struct ldapsessctl      **controls;
           );

           int ldap_session_s(
                   LDAP                    *ld;
                   struct ldapsessctl      **controls;
                   LDAPMessage             **result;
           );

Parameters are:

ld       The session handle.

controls A NULL-terminated array of pointers to ldapsessctl structures
         indicating the requested session controls.

result   A result parameter that will be filled in with the result of
         the session control operation. This parameter is suitable for
         passing to ldap_parse_session_result(), described below.

The following constants are defined and may be assigned to the sc_type
field in the ldapsessctl structure. The controls have the following
meanings.

LDAP_SESSION_ATTR_SIZELIMIT
     This control sets a limit on the size of any attribute value the
     server will return to the client. The sc_value field should point
     to a string containing the decimal string representation of the



Expires 4/97                                                    [Page 7]


LDAP API                                                    October 1996


     size limit in bytes.

LDAP_SESSION_NO_COPY
     This control instructs the server not to perform operations against
     copies of the data, only to use the master version.  It can be set
     to LDAP_OPT_ON or LDAP_OPT_OFF.

LDAP_SESSION_PARTIAL_COPY
     This control instructs the server that it should return search
     results from partial replicas of the directory.  It can be set to
     LDAP_OPT_ON or LDAP_OPT_OFF.

LDAP_SESSION_REFERRING_SERVER
     This control tells the server which server (if any) referred the
     client to the server. It is useful in debugging, and should contain
     a URL.

LDAP_SESSION_NO_CHAINING
     This control instructs the server not to chain requests on the
     client's behalf. It should be set to either LDAP_OPT_ON or
     LDAP_OPT_OFF.

LDAP_SESSION_SUPPORTED_PROTOCOL
     This control instructs the server in which protocols the client
     supports for returned referrals. It should be a null-terminated
     array of string protocol names, such as "ldap", "cldap", etc.

LDAP_SESSION_ALIAS_ON_UPDATE
     This control instructs the server that it should follow aliases on
     update (add, delete, modify, modify dn) operations.  It should be
     set to LDAP_OPT_ON or LDAP_OPT_OFF.

LDAP_SESSION_MANAGE_SERVER
     This control instructs the server that the client wants to manage
     server data, such as knowledge references, rather than follow the
     links they provide. It should be set to LDAP_OPT_ON or
     LDAP_OPT_OFF.

LDAP_SESSION_PREFERRED_LANGUAGE
     This control tells the server the list of the client's preferred
     languages.

ldap_session_s() is synchronous and returns an LDAP error code indicat-
ing the success or failure of the operation.

ldap_session() is asynchronous and returns the message id of the opera-
tion it initiates, or -1 in case of trouble. The result of the operation
may be obtained by a subsequent call to ldap_result().



Expires 4/97                                                    [Page 8]


LDAP API                                                    October 1996


5.4.  Authenticating to the directory

ldap_bind() and friends are used to authenticate an LDAP client to an
LDAP directory server.

The ldap_extended_bind() and ldap_extended_bind_s() calls can be used to
do general and extensible authentication over LDAP.  The routines both
take the dn to bind as, the method to use, as a dotted-string represen-
tation of an OID identifying the method, and a struct berval holding the
credentials. The special constant value LDAP_AUTH_SIMPLE_OID can be
passed to request simple authentication, or the simplified routines
ldap_simple_bind() or ldap_simple_bind_s() can be used.

           typedef struct ldapmsg LDAPMessage;

           int ldap_extended_bind( LDAP *ld, char *dn, char *methodoid,
                   struct berval *credentials );

           int ldap_extended_bind_s( LDAP *ld, char *dn, char *methodoid,
                   struct berval *credentials, LDAPMessage **result );

           int ldap_simple_bind( LDAP *ld, char *dn, char *passwd );

           int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd );

   The use of the following routines is deprecated:

           int ldap_bind( LDAP *ld, char *dn, char *cred, int method );

           int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );

           int ldap_kerberos_bind( LDAP *ld, char *dn );

           int ldap_kerberos_bind_s( LDAP *ld, char *dn );

Parameters are:

ld     The connection handle.

dn     The name of the entry to bind as.

methodoid
       Either LDAP_AUTH_SIMPLE_OID, to get simple authentication, or a
       dotted text string representing an OID identifying the bind
       method.

credentials
       The credentials with which to authenticate. Arbitrary credentials



Expires 4/97                                                    [Page 9]


LDAP API                                                    October 1996


       can be passed using this parameter. The format and content of the
       credentials depends on the setting of the methodoid parameter.

result For the synchronous version of extended bind,
       ldap_extended_bind_s(), this is a result-parameter that will be
       set to the LDAPMessage containing the result of the bind. This
       result is suitable for passing to ldap_parse_result() or
       ldap_parse_bind_result(), both described below.

passwd For ldap_simple_bind(), the password to compare to the entry's
       userPassword attribute.

Additional parameters for the deprecated routines are not described.
Interested readers are referred to RFC 1823.

Synchronous versions of the routines have names that end in _s.  These
routines return the result of the bind operation, either the constant
LDAP_SUCCESS if the operation was successful, or another LDAP error code
if it was not. See the section below on error handling for more informa-
tion about possible errors and how to interpret them.

Asynchronous versions of these routines return the message id of the
bind operation initiated. A subsequent call to ldap_result(), described
below, can be used to obtain the result of the bind. In case of error,
these routines will return -1, setting the session error parameters in
the LDAP structure appropriately.

Note that no other operations over the connection should be attempted
before a bind call has successfully completed. Subsequent bind calls can
be used to re-authenticate over the same connection.

5.5.  Closing the connection

ldap_unbind() is used to unbind from the directory, close the connec-
tion, and dispose of the connection handle.

           int ldap_unbind( LDAP *ld );

Parameters are:

ld   The connection handle.

ldap_unbind() works synchronously, unbinding from the directory, closing
the connection, and freeing up the ld structure before returning.
ldap_unbind() returns LDAP_SUCCESS (or another LDAP error code if the
request cannot be sent to the LDAP server).  After a call to
ldap_unbind(), the ld connection handle is invalid.




Expires 4/97                                                   [Page 10]


LDAP API                                                    October 1996


5.6.  Searching

ldap_search() and friends are used to search the LDAP directory, return-
ing a requested set of attributes for each entry matched.  There are
three variations.

           struct timeval {
                   long    tv_sec;
                   long    tv_usec;
           };
           int ldap_search(
                   LDAP    *ld,
                   char    *base,
                   int     scope,
                   char    *filter,
                   char    *attrs[],
                   int     attrsonly
           );
           int ldap_search_s(
                   LDAP            *ld,
                   char            *base,
                   int             scope,
                   char            *filter,
                   char            *attrs[],
                   int             attrsonly,
                   LDAPMessage     **res
           );
           int ldap_search_st(
                   LDAP            *ld,
                   char            *base,
                   int             scope,
                   char            *filter,
                   char            *attrs[],
                   int             attrsonly,
                   struct timeval  *timeout,
                   LDAPMessage     **res
           );

Parameters are:

ld        The connection handle.

base      The dn of the entry at which to start the search.

scope     One of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, or
          LDAP_SCOPE_SUBTREE, indicating the scope of the search.

filter    A character string as described in RFC 1960 [3], representing



Expires 4/97                                                   [Page 11]


LDAP API                                                    October 1996


          the search filter.

attrs     A NULL-terminated array of strings indicating which attributes
          to return for each matching entry. Passing NULL for this
          parameter causes all available attributes to be retrieved.

attrsonly A boolean value that should be zero if both attribute types
          and values are to be returned, non-zero if only types are
          wanted.

timeout   For the ldap_search_st() call, this specifies the local search
          timeout value.

res       For the synchronous calls, this is a result parameter which
          will contain the results of the search upon completion of the
          call.

There are three options in the ld connection handle which control how
the search is performed. They are:

LDAP_OPT_SIZELIMIT
             A limit on the number of entries to return from the search.
             A value of zero means no limit.

LDAP_OPT_TIMELIMIT
             A limit on the number of seconds to spend on the search. A
             value of zero means no limit.

LDAP_OPT_DEREFOne of LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING,
             LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS, specifying how
             aliases should be handled during the search. The
             LDAP_DEREF_SEARCHING value means aliases should be derefer-
             enced during the search but not when locating the base
             object of the search. The LDAP_DEREF_FINDING value means
             aliases should be dereferenced when locating the base
             object but not during the search.

An asynchronous search is initiated by calling ldap_search(). It returns
the message id of the initiated search. The results of the search can be
obtained by a subsequent call to ldap_result().  The results can be
parsed by the result parsing routines described in detail later.  In
case of error, -1 is returned and the session error parameters in the
LDAP structure are set appropriately.

A synchronous search is performed by calling ldap_search_s() or
ldap_search_st(). The routines are identical, except that
ldap_search_st() takes an additional parameter specifying a local
timeout for the search.  Both routines return an indication of the



Expires 4/97                                                   [Page 12]


LDAP API                                                    October 1996


result of the search, either LDAP_SUCCESS or some error indication (see
Error Handling below).  The entries returned from the search (if any)
are contained in the res parameter. This parameter is opaque to the
caller.  Entries, attributes, values, etc., should be extracted by cal-
ling the parsing routines described below. The results contained in res
should be freed when no longer in use by calling ldap_msgfree(),
described later.

5.7.  Reading an Entry

LDAP does not support a read operation directly. Instead, this operation
is emulated by a search with base set to the DN of the entry to read,
scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". attrs
contains the list of attributes to return.

5.8.  Listing the Children of an Entry

LDAP does not support a list operation directly. Instead, this operation
is emulated by a search with base set to the DN of the entry to list,
scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)".
attrs contains the list of attributes to return for each child entry.

5.9.  Returning Search Results a Page at a Time

New to LDAPv3 is support in the protocol for retrieving search results a
page at a time. The ldap_search_init_page() and ldap_search_get_page()
routines provide an API interface to this capability.

           typedef struct ldapsearch LDAPSearch;

           LDAPSearch *ldap_search_init_page(
                   LDAP                    *ld,
                   char                    *base,
                   int                     scope,
                   char                    *filter,
                   char                    *attrs[],
                   int                     attrsonly,
                   struct ldapsortkey      **sortkeys
           );

           int ldap_search_get_page(
                   LDAP            *ld,
                   LDAPSearch      *searchhandle,
                   int             startatentry,
                   int             pagesize,
                   int             *totalcount
           );




Expires 4/97                                                   [Page 13]


LDAP API                                                    October 1996


           int ldap_search_get_page_s(
                   LDAP            *ld,
                   LDAPSearch      *searchhandle,
                   int             startatentry,
                   int             pagesize,
                   int             *totalcount,
                   LDAPMessage     **result
           );

           int ldap_search_abandon_page(
                   LDAP            *ld,
                   LDAPSearch      *searchhandle
           );

The parameters to ldap_search_init_page() are exactly the same as those
to ldap_search(), except for the additional sortkeys parameter. This
parameter and parameters to ldap_search_get_page() are:

ld       The connection handle.

sortkeys If the results of the search are desired back in sorted order,
         this parameter is a NULL-terminated array of pointers to struct
         sortkeys, indicating the attribute types and matching rules by
         which the results are to be sorted. If this parameter is NULL,
         the default value for sortkeys, if any, is taken from the LDAP
         session parameter LDAP_OPT_SORTKEYS.

searchhandle
         A handle to an opaque data type returned from a successful call
         to ldap_search_init_page(). This parameter should be passed to
         all subsequent calls to ldap_search_get_page() or
         ldap_search_get_page_s() pertaining to the same search.

startatentry
         The number of entries in the search result before which the
         page to be retrieved begins. To start at the beginning of the
         search result, supply 0 (zero) for startatentry. To begin in
         the middle of a 100-entry search result, supply 50 for starta-
         tentry.

pagesize The number of entries that should be returned in the page.  No
         more than this many entries will be returned from the search,
         though fewer can be returned if the page extends beyond the
         total size of the result set.

totalcount  A result-parameter that will be set to the total number of
            entries in the search result. This parameter may change on
            subsequent calls to ldap_search_get_page() or



Expires 4/97                                                   [Page 14]


LDAP API                                                    October 1996


            ldap_search_get_page_s(), if the size of the result set
            changes (for example, because of additions or deletions to
            the directory between calls).

result   A result-parameter that will be set to an LDAPMessage contain-
         ing the result of the search, which will be either a "page" of
         entries, suitable for passing to ldap_first_entry() and friends
         (just like a result from ldap_search_s()), or or an LDAPMessage
         containing an explanation of an error that occurred, suitable
         for passing to ldap_parse_result().

ldap_search_init_page() returns a pointer to an opaque data structure
representing the search, or NULL on error. The non-NULL return value
should be passed to a subsequent call to ldap_search_get_page() or
ldap_search_get_page_s() to retrieve the actual pages of results from
the search.

ldap_search_get_page_s() is synchronous and returns the LDAP error code
resulting from the search operation. This code can be interpreted by
ldap_perror() and friends.

ldap_search_get_page() is asynchronous and returns the message id of the
request it initiates, or -1 on  error.  The result of the operation can
be obtained by calling ldap_result().

ldap_search_abandon_page() abandons the current search-page sequence
begun by calling ldap_search_init_page(). It frees the searchhandle
structure, which is invalid after the call.

5.10.  Comparing a Value Against an Entry

The ldap_compare() and ldap_compare_s() routines are used to compare a
given attribute value assertion against an LDAP entry.

           int ldap_compare(
                   LDAP            *ld,
                   const char      *dn,
                   const char      *attr,
                   struct berval   *bvalue
           );

           int ldap_compare_s(
                   LDAP            *ld,
                   const char      *dn,
                   const char      *attr,
                   struct berval   *bvalue,
                   char            **matchedtype
           );



Expires 4/97                                                   [Page 15]


LDAP API                                                    October 1996


Parameters are:

ld       The connection handle.

dn       The name of the entry to compare against.

attr     The attribute to compare against.

bvalue   The attribute value to compare against those found in the
         entry. This parameter is a pointer to a struct berval so it is
         possible to compare binary values.

matchedtype
         This result-parameter will be set to the attribute type actu-
         ally used to match the compare. This is useful if attribute
         sub-typing is involved, and the attr given is a parent type. If
         no attribute sub-typing is involed (or is not supported, as in
         the case of LDAPv2 servers), this result-parameter will be set
         to NULL.

5.11.  Modifying an entry

The ldap_modify() and ldap_modify_s() routines are used to modify an
existing LDAP entry.

           typedef struct ldapmod {
                   int             mod_op;
                   char            *mod_type;
                   union {
                           char            **modv_strvals;
                           struct berval   **modv_bvals;
                   } mod_vals;
           } LDAPMod;
           #define mod_values      mod_vals.modv_strvals
           #define mod_bvalues     mod_vals.modv_bvals

           int ldap_modify( LDAP *ld, char *dn, LDAPMod *mods[] );

           int ldap_modify_s( LDAP *ld, char *dn, LDAPMod *mods[] );

Parameters are:

ld       The connection handle;

dn       The name of the entry to modify;

mods     A NULL-terminated array of modifications to make to the entry.




Expires 4/97                                                   [Page 16]


LDAP API                                                    October 1996


The fields in the LDAPMod structure have the following meanings:

mod_op   The modification operation to perform. It should be one of
         LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. This field
         also indicates the type of values included in the mod_vals
         union. It is ORed with LDAP_MOD_BVALUES to select the
         mod_bvalues form. Otherwise, the mod_values form is used.

mod_type The type of the attribute to modify.

mod_vals The values (if any) to add, delete, or replace. Only one of the
         mod_values or mod_bvalues variants should be used, selected by
         ORing the mod_op field with the constant LDAP_MOD_BVALUES.
         mod_values is a NULL-terminated array of zero-terminated
         strings and mod_bvalues is a NULL-terminated array of berval
         structures that can be used to pass binary values such as
         images.

For LDAP_MOD_ADD modifications, the given values  are  added to  the
entry,  creating  the  attribute if necessary.  For LDAP_MOD_DELETE
modifications, the given values are deleted from the entry, removing the
attribute if no values remain. If the entire attribute is to  be
deleted,  the  mod_vals field should be set to NULL.  For
LDAP_MOD_REPLACE modifications, the attribute will have the listed
values after the modification, having been created if necessary. All
modifications are performed in the order in which they are listed.

ldap_modify_s() is synchronous and returns the LDAP error code resulting
from the modify operation. This code can be interpreted by ldap_perror()
and friends.

ldap_modify() is asynchronous and returns the message id of the request
it initiates, or -1 on error. The result of the operation can be
obtained by calling ldap_result().

5.12.  Modifying the Name of an Entry

In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to
change the name of an LDAP entry. They could only be used to change the
least significant component of a name (the RDN or relative distinguished
name). LDAPv3 provides the Modify DN protocol operation that allows more
general name change access. The ldap_moddn() and ldap_moddn_s() routines
are used to change the name of an entry, and the use of the
ldap_modrdn() and ldap_modrdn_s() routines is deprecated.

           int ldap_moddn(
                   LDAP    *ld,
                   char    *dn,



Expires 4/97                                                   [Page 17]


LDAP API                                                    October 1996


                   char    *newdn,
                   int     deleteoldrdn
           );
           int ldap_moddn_s(
                   LDAP    *ld,
                   char    *dn,
                   char    *newdn,
                   int     deleteoldrdn
           );

   Use of the following routines is deprecated.

           int ldap_modrdn(
                   LDAP    *ld,
                   char    *dn,
                   char    *newrdn,
                   int     deleteoldrdn
           );
           int ldap_modrdn_s(
                   LDAP    *ld,
                   char    *dn,
                   char    *newrdn,
                   int     deleteoldrdn
           );

Parameters are:

ld       The session handle.

dn       The name of the entry whose DN is to be changed.

newdn    The new DN to give the entry.

deleteoldrdn
         This parameter only has meaning on the modify DN routines if
         the newdn has a different RDN than the old DN. It is a boolean
         value, if non-zero indicating that the old RDN value(s) should
         be removed, if zero indicating that the old RDN value(s) should
         be retained as non-distinguished values of the entry.

Parameters of the deprecated routines are not described.  Interested
readers are referred to RFC 1823.

The ldap_moddn_s() routine is synchronous, returning the LDAP error code
indicating the outcome of the operation.

The ldap_moddn() routine is asynchronous, returning the message id of
the operation it initiates, or -1 in case of trouble. The result of the



Expires 4/97                                                   [Page 18]


LDAP API                                                    October 1996


operation can be obtained by calling ldap_result().

5.13.  Adding an entry

ldap_add() and ldap_add_s() are used to add entries to the LDAP direc-
tory.

           int ldap_add( LDAP *ld, char *dn, LDAPMod *attrs[] );

           int ldap_add_s( LDAP *ld, char *dn, LDAPMod *attrs[] );

Parameters are:

ld    The session handle.

dn    The name of the entry to add.

attrs The entry's attributes, specified using the LDAPMod structure
      defined for ldap_modify(). The mod_type and mod_vals fields should
      be filled in.  The mod_op field is ignored unless ORed with the
      constant LDAP_MOD_BVALUES, used to select the mod_bvalues case of
      the mod_vals union.

Note that the parent of the entry must already exist.

ldap_add_s() is synchronous, returning the LDAP error code indicating
the outcome of the operation.

ldap_add() is asynchronous, returning the message id of the operation it
initiates, or -1 in case of trouble. The result of the operation can be
obtained by calling ldap_result().

5.14.  Deleting an entry

ldap_delete() and ldap_delete_s() are used to delete entries from the
LDAP directory.

           int ldap_delete( LDAP *ld, char *dn );

           int ldap_delete_s( LDAP *ld, char *dn );

Parameters are:

ld       The session handle.

dn       The name of the entry to delete.

Note that the entry to delete must be a leaf entry (i.e., it must have



Expires 4/97                                                   [Page 19]


LDAP API                                                    October 1996


no children). Deletion of entire subtrees is not supported by LDAP.

ldap_delete_s() is synchronous, returning the LDAP error code indicating
the outcome of the operation.

ldap_delete() is asynchronous, returning the message id of the operation
it initiates, or -1 in case of trouble. The result of the operation can
be obtained by calling ldap_result().

5.15.  Extended Operations

The ldap_extended() and ldap_extended_s() routines allow extended LDAP
operations to be passed to the server, providing a general protocol
extensibility mechanism.

           int ldap_extended(
                   LDAP            *ld,
                   char            *requestoid,
                   struct berval   *requestdata
           );

           int ldap_extended_s(
                   LDAP            *ld,
                   char            *requestoid,
                   struct berval   *requestdata,
                   LDAPMessage     **result
           );

Parameters are:

ld       The session handle.

requestoidThe dotted-oid text string naming the request.

requestdata
         The arbitrary data required by the operation.

result   A result parameter that will be filled in with the result of
         the operation, suitable for passing to
         ldap_parse_extended_result().

The ldap_extended_s() routine is synchronous and returns an LDAP error
code indicating the success or failure of the extended operation.

The ldap_extended() routine is asynchronous and returns the message id
of the operation it initiates, or -1 in case of trouble. The result of
the operation can be obtained by calling ldap_result().




Expires 4/97                                                   [Page 20]


LDAP API                                                    October 1996


6.  Calls for abandoning an operation

ldap_abandon() is used to abandon an operation in progress.

           int ldap_abandon( LDAP *ld, int msgid );


ld     The session handle.

msgid  The message id of the request to be abandoned.

ldap_abandon() abandons the operation with message id msgid. It returns
zero if the abandon was successful, -1 otherwise. After a successful
call to ldap_abandon(), results with the given message id are never
returned from a call to ldap_result().

7.  Calls for obtaining results

ldap_result() is used to obtain the result of a previous asynchronously
initiated operation. ldap_msgfree() frees the results obtained from a
previous call to ldap_result(), or a synchronous search routine.
ldap_msgtype() returns the type of an LDAP message.

           int ldap_result(
                   LDAP            *ld,
                   int             msgid,
                   int             all,
                   struct timeval  *timeout,
                   LDAPMessage     **res
           );

           int ldap_msgfree( LDAPMessage *res );

           int ldap_msgtype( LDAPMessage *res );

Parameters are:

ld       The connection handle;

msgid    The message id of the operation whose results are to be
         returned, or the constant LDAP_RES_ANY if any result is
         desired;

all      A boolean parameter that only has meaning for search results.
         If non-zero it indicates that all results of a search should be
         retrieved before any are returned. If zero, search results
         (entries) will be returned one at a time as they arrive;




Expires 4/97                                                   [Page 21]


LDAP API                                                    October 1996


timeout  A timeout specifying how long to wait for results to be
         returned.  A NULL value causes ldap_result() to block until
         results are available.  A timeout value of zero seconds speci-
         fies a polling behavior;

res      For ldap_result(), a result parameter that will contain the
         result(s) of the operation. For ldap_msgfree(), the result
         chain to be freed, obtained from a previous call to
         ldap_result(), ldap_search_s(), ldap_search_st(), or
         ldap_search_get_page_s().

Upon successful completion, ldap_result() returns the type of the result
returned in the res parameter. This will be one of the following con-
stants.

             LDAP_RES_BIND
             LDAP_RES_SEARCH_ENTRY
             LDAP_RES_SEARCH_REFERENCE     -- new
             LDAP_RES_SEARCH_RESULT
             LDAP_RES_MODIFY
             LDAP_RES_ADD
             LDAP_RES_DELETE
             LDAP_RES_MODRDN
             LDAP_RES_COMPARE
             LDAP_RES_SESSION              -- new
             LDAP_RES_EXTENDED             -- new

ldap_result() returns 0 if the timeout expired and -1 if an error
occurs, in which case the error parameters of the LDAP session handle
will be set accordingly.

ldap_msgfree() frees the result structure pointed to be res and returns
the type of the message it freed.

ldap_msgtype() returns the type of the LDAP message it is passed as a
parameter. The type will be one of the types listed above, or -1 on
error.

8.  Calls for Error and Result Handling

The following calls are used to interpret errors returned by other LDAP
API routines.

           int ldap_parse_result(
                   LDAP            *ld,
                   LDAPMessage     *result,
                   char            **matched,
                   char            **errmsg,



Expires 4/97                                                   [Page 22]


LDAP API                                                    October 1996


                   char            ***referrals
           );
           int ldap_parse_bind_result(
                   LDAP            *ld,
                   LDAPMessage     *result,
                   char            **matched,
                   char            **errmsg,
                   char            ***referrals,
                   int             *version,
                   char            *serverurl,
                   struct berval   **servercreds
           );
           int ldap_parse_search_result(
                   LDAP            *ld,
                   LDAPMessage     *result,
                   char            **matched,
                   char            **errmsg,
                   char            ***referrals,
                   int             *totalcount
           );
           int ldap_parse_compare_result(
                   LDAP            *ld,
                   LDAPMessage     *result,
                   char            **matched,
                   char            **errmsg,
                   char            ***referrals,
                   char            **matchedtype
           );
           int ldap_parse_session_result(
                   LDAP            *ld,
                   LDAPMessage     *result,
                   char            **matched,
                   char            **errmsg,
                   char            ***referrals,
                   char            ***unsupported
           );
           int ldap_parse_extended_result(
                   LDAP            *ld,
                   LDAPMessage     *result,
                   char            **matched,
                   char            **errmsg,
                   char            ***referrals,
                   char            **resultoid,
                   struct berval   **resultdata
           );

           char *ldap_err2string( int err );




Expires 4/97                                                   [Page 23]


LDAP API                                                    October 1996


           void ldap_perror( LDAP *ld, char *msg );

   The use of the following routines is deprecated.

           int ldap_result2error(
                   LDAP            *ld,
                   LDAPMessage     *result,
                   int             freeit
           );

Parameters are:

ld       The connection handle.

result   The result of an LDAP operation as returned by ldap_result() or
         one of the synchronous API operation calls.

matched  In the case of a return of LDAP_NO_SUCH_OBJECT, this result
         parameter will be filled in with a DN indicating how much of
         the name in the request was recognized. NULL may be passed to
         ignore this field.

errmsg   This result parameter will be filled in with the contents of
         the error message field from the LDAPResult message. NULL may
         be passed to ignore this field.

referralsThis result parameter will be filled in with the contents of
         the referrals field from the LDAPResult message, indicating
         zero or more alternate LDAP servers where the request should be
         retried. NULL may be passed to ignore this field.

version  For bind results, this result parameter will be filled in with
         the version number returned by the LDAP server, indicating the
         highest version number the server supports. NULL may be passed
         to ignore this field.

serverurlFor bind results, this result parameter will be filled in with
         the official LDAP URL for accessing this server, if given. NULL
         may be passed to ignore this field.

servercreds
         For bind results, this result parameter will be filled in with
         the credentials passed back by the server for mutual authenti-
         cation, if given. NULL may be passed to ignore this field.

totalcountFor search results, this result parameter will be filled in
         with the total count from a paged search request. NULL may be
         passed to ignore this field.



Expires 4/97                                                   [Page 24]


LDAP API                                                    October 1996


matchedtype
         For compare results, this result parameter will be filled in
         with the name of the attribute type actually used in the com-
         pare match. NULL may be passed to ignore this field.

unsupported
      For session results, this result parameter will be filled in with
      a NULL-terminated array of string OIDs identifying unsupported
      session controls from the corresponding session request.  NULL may
      be passed to ignore this field.

resultoidFor extended results, this result parameter will be filled in
         with the dotted-OID text representation of the name of the
         extended operation response.  NULL may be passed to ignore this
         field.

resultdataFor extended results, this result parameter will be filled in
         with a pointer to a struct berval containing the data in the
         extended operation response. NULL may be passed to ignore this
         field.

err      For ldap_err2string(), an LDAP error code, as returned by
         ldap_result2error() or one of the synchronous API operation
         calls.

msg      For ldap_perror(), a message to be displayed before the LDAP
         error message.

Parameters for the deprecated calls are not described.  Interested
readers are referred to RFC 1823.

All of the ldap_parse*_result() routines return an LDAP error code indi-
cating the outcome of the operation. This is one of the following con-
stants:

           LDAP_SUCCESS
           LDAP_OPERATIONS_ERROR
           LDAP_PROTOCOL_ERROR
           LDAP_TIMELIMIT_EXCEEDED
           LDAP_SIZELIMIT_EXCEEDED
           LDAP_COMPARE_FALSE
           LDAP_COMPARE_TRUE
           LDAP_STRONG_AUTH_NOT_SUPPORTED
           LDAP_STRONG_AUTH_REQUIRED
           LDAP_REFERRAL                           -- new
           LDAP_ADMIN_LIMIT_EXCEEDED               -- new
           LDAP_UNAVAILALBLE_EXTENSION             -- new
           LDAP_NO_SUCH_ATTRIBUTE



Expires 4/97                                                   [Page 25]


LDAP API                                                    October 1996


           LDAP_UNDEFINED_TYPE
           LDAP_INAPPROPRIATE_MATCHING
           LDAP_CONSTRAINT_VIOLATION
           LDAP_TYPE_OR_VALUE_EXISTS
           LDAP_INVALID_SYNTAX
           LDAP_NO_SUCH_OBJECT
           LDAP_ALIAS_PROBLEM
           LDAP_INVALID_DN_SYNTAX
           LDAP_IS_LEAF
           LDAP_ALIAS_DEREF_PROBLEM
           LDAP_INAPPROPRIATE_AUTH
           LDAP_INVALID_CREDENTIALS
           LDAP_INSUFFICIENT_ACCESS
           LDAP_BUSY
           LDAP_UNAVAILABLE
           LDAP_UNWILLING_TO_PERFORM
           LDAP_LOOP_DETECT
           LDAP_NAMING_VIOLATION
           LDAP_OBJECT_CLASS_VIOLATION
           LDAP_NOT_ALLOWED_ON_NONLEAF
           LDAP_NOT_ALLOWED_ON_RDN
           LDAP_ALREADY_EXISTS
           LDAP_NO_OBJECT_CLASS_MODS
           LDAP_RESULTS_TOO_LARGE
           LDAP_AFFECTS_MULTIPLE_SERVERS           -- new
           LDAP_OTHER
           LDAP_SERVER_DOWN
           LDAP_LOCAL_ERROR
           LDAP_ENCODING_ERROR
           LDAP_DECODING_ERROR
           LDAP_TIMEOUT
           LDAP_AUTH_UNKNOWN
           LDAP_FILTER_ERROR
           LDAP_USER_CANCELLED
           LDAP_PARAM_ERROR
           LDAP_NO_MEMORY
           LDAP_CONNECT_ERROR

In case of trouble (failure to parse the result), -1 is returned.

ldap_err2string() is used to convert a numeric LDAP error code, as
returned by one of the ldap_parse*_result() routines, or one of the syn-
chronous API operation calls, into an informative NULL-terminated char-
acter string message describing the error.  It returns a pointer to
static data.

ldap_perror() is used to print the message supplied in msg, followed by
an indication of the error contained in the ld_errno field of the ld



Expires 4/97                                                   [Page 26]


LDAP API                                                    October 1996


connection handle, to standard error.

9.  Calls for Parsing Search Entries

The following calls are used to parse the entries and references
returned by ldap_search() and friends. These results are returned in an
opaque structure that should only be accessed by calling the routines
described below. Routines are provided to step through the entries and
references returned, step through the attributes of an entry, retrieve
the name of an entry, and retrieve the values associated with a given
attribute in an entry.

9.1.  Stepping Through a Set of Entries

The ldap_first_entry() and ldap_next_entry() routines are used to step
through a set of entries and references in a search result.
ldap_count_entries() is used to count the number of entries returned.
ldap_count_references() is used to count the number of references
returned. ldap_msgtype(), described above, can be used to distinguish
between entries and references.

           LDAPMesage *ldap_first_entry( LDAP *ld, LDAPMessage *res );

           LDAPMesage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );

           int ldap_count_entries( LDAP *ld, LDAPMessage *res );

           int ldap_count_references( LDAP *ld, LDAPMessage *res );

Parameters are:

ld     The connection handle;

res    The search result, as obtained by a call to one of the synchro-
       nous search routines or ldap_result();

entry  The entry returned by a previous call to ldap_first_entry() or
       ldap_next_entry().

ldap_first_entry() and ldap_next_entry() will return NULL when no more
entries or references exist in the result set to be returned.  NULL is
also returned if an error occurs while stepping through the entries, in
which case the error parameters in the ld session handle will be set to
indicate the error.

ldap_count_entries() returns the number of entries contained in a chain
of entries. It can also be used to count the number of entries that
remain in a chain if called with an entry or reference returned by



Expires 4/97                                                   [Page 27]


LDAP API                                                    October 1996


ldap_first_entry() or ldap_next_entry().

ldap_count_refernces() returns the number of references contained in a
chain of search results. It can also be used to count the number of
references that remain in a chain if called with an entry or references
returned by ldap_first_entry() or ldap_next_entry().

9.2.  Stepping Through the Attributes of an Entry

The ldap_first_attribute() and ldap_next_attribute() calls are used to
step through the list of attribute types returned with an entry.

           char *ldap_first_attribute(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   BerElement      **ptr
           );

           char *ldap_next_attribute(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   BerElement      *ptr
           );

           void ldap_memfree( char *mem );

Parameters are:

ld     The connection handle;

entry  The entry whose attributes are to be stepped through, as returned
       by ldap_first_entry() or ldap_next_entry();

ptr    In ldap_first_attribute(), the address of a pointer used inter-
       nally to keep track of the current position in the entry. In
       ldap_next_attribute(), the pointer returned by a previous call to
       ldap_first_attribute().

mem    A pointer to memory allocated by the LDAP library, such as the
       attribute names returned by ldap_first_attribute() and
       ldap_next_attribute, or the DN returned by ldap_get_dn().

ldap_first_attribute() and ldap_next_attribute() will return NULL when
the end of the attributes is reached, or if there is an error, in which
case the error parameters in the ld session handle will be set to indi-
cate the error.

Both routines return a pointer to an allocated buffer containing the



Expires 4/97                                                   [Page 28]


LDAP API                                                    October 1996


current attribute name. This should be freed when no longer in use by
calling ldap_memfree().

ldap_first_attribute() will allocate and return in ptr a pointer to a
BerElement used to keep track of the current position. This pointer
should be passed in subsequent calls to ldap_next_attribute() to step
through the entry's attributes. After a set of calls to
ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it
should be freed by calling ber_free( ptr, 0 ). Note that it is very
important to pass the second parameter as 0 (zero) in this call.

The attribute names returned are suitable for passing in a call to
ldap_get_values() and friends to retrieve the associated values.

9.3.  Retrieving the Values of an Attribute

ldap_get_values() and ldap_get_values_len() are used to retrieve the
values of a given attribute from an entry. ldap_count_values() and
ldap_count_values_len() are used to count the returned values.
ldap_value_free() and ldap_value_free_len() are used to free the values.

           typedef struct berval {
                   unsigned long   bv_len;
                   char            *bv_val;
           };

           char **ldap_get_values(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   char            *attr
           );

           struct berval **ldap_get_values_len(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   char            *attr
           );

           int ldap_count_values( char **vals );

           int ldap_count_values_len( struct berval **vals );

           int ldap_value_free( char **vals );

           int ldap_value_free_len( struct berval **vals );

Parameters are:




Expires 4/97                                                   [Page 29]


LDAP API                                                    October 1996


ld     The connection handle.

entry  The entry from which to retrieve values, as returned by
       ldap_first_entry() or ldap_next_entry().

attr   The attribute whose values are to be retrieved, as returned by
       ldap_first_attribute() or ldap_next_attribute(), or a caller-
       supplied string (e.g., "mail").

vals   The values returned by a previous call to ldap_get_values() or
       ldap_get_values_len().

Two forms of the various calls are provided. The first form is only
suitable for use with non-binary character string data only. The second
_len form is used with any kind of data.

Note that the values returned are dynamically allocated and should be
freed by calling either ldap_value_free() or ldap_value_free_len() when
no longer in use.

9.4.  Retrieving the name of an entry

ldap_get_dn() is used to retrieve the name of an entry.
ldap_explode_dn() is used to break up the name into its component parts.
ldap_dn2ufn() is used to convert the name into a more "user friendly"
format.

           char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );

           char **ldap_explode_dn( char *dn, int notypes );

           char **ldap_explode_rdn( char *rdn, int notypes );

           char *ldap_dn2ufn( char *dn );

Parameters are:

ld      The connection handle.

entry   The entry whose name is to be retrieved, as returned by
        ldap_first_entry() or ldap_next_entry().

dn      The dn to explode, such as returned by ldap_get_dn().

rdn     The rdn to explode, such as returned in the components of the
        array returned by ldap_explode_dn().

notypes A boolean parameter, if non-zero indicating that the dn or rdn



Expires 4/97                                                   [Page 30]


LDAP API                                                    October 1996


        components should have their type information stripped off
        (i.e., "cn=Babs" would become "Babs").

ldap_get_dn() will return NULL if there is some error parsing the dn,
setting error parameters in the ld session handle to indicate the error.
It returns a pointer to malloc'ed space that the caller should free by
calling free() when it is no longer in use.  Note the format of the DNs
returned is given by [4].

ldap_explode_dn() returns a NULL-terminated char * array containing the
RDN components of the DN supplied, with or without types as indicated by
the notypes parameter. The array returned should be freed when it is no
longer in use by calling ldap_value_free().

ldap_explode_rdn() returns a NULL-terminated char * array containing the
components of the RDN supplied, with or without types as indicated by
the notypes parameter. The array returned should be freed when it is no
longer in use by calling ldap_value_free().

ldap_dn2ufn() converts the DN into the user friendly format described in
[5]. The UFN returned is malloc'ed space that should be freed by a call
to free() when no longer in use.

10.  Security Considerations

LDAP supports security through protocol-level authentication, using
clear-text passwords or other more secure mechanisms.  It also supports
running over SSL, which provides strong security at the transport layer.

11.  Acknowledgements

Many members of the IETF ASID working group as well as members of the
Internet at large have provided useful comments and suggestions that
have been incorporated into this revision.

This original material upon which this revision is based was based upon
work supported by the National Science Foundation under Grant No.  NCR-
9416667.

12.  Bibliography

[1]  The Directory: Selected Attribute Syntaxes.  CCITT, Recommendation
     X.520.

[2]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
     Access Protocol: Standard and Pilot Attribute Definitions", Inter-
     net Draft draft-ietf-asid-ldapv3-attributes-03.txt, October 1996




Expires 4/97                                                   [Page 31]


LDAP API                                                    October 1996


[3]  T. Howes, "A String Representation of LDAP Search Filters," RFC
     1960, June 1996.

[4]  S. Kille, "A String Representation of Distinguished Names," RFC
     1779, March 1995.

[5]  S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
     ing," RFC 1781, March 1995.

[7]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
     (v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-03.txt,
     October 1996.

13.  Author's Addresses

   Tim Howes
   Netscape Communications Corp.
   501 E. Middlefield Rd.
   Mountain View, CA 94043
   USA
   +1 415 937-3419
   howes@netscape.com

   Mark Smith
   Netscape Communications Corp.
   501 E. Middlefield Rd.
   Mountain View, CA 94043
   USA
   +1 313 937-3477
   mcs@netscape.com

14.  Appendix A - Sample LDAP API Code

   #include <ldap.h>

   main()
   {
           LDAP            *ld;
           LDAPMessage     *res, *e;
           int             i;
           char            *a, *dn;
           BerElement      *ptr;
           char            **vals;

           /* open a connection */
           if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
                   exit( 1 );




Expires 4/97                                                   [Page 32]


LDAP API                                                    October 1996


           /* authenticate as nobody */
           if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
                   ldap_perror( ld, "ldap_simple_bind_s" );
                   exit( 1 );
           }

           /* search for entries with cn of "Babs Jensen", return all attrs  */
           if ( ldap_search_s( ld, "o=University of Michigan, c=US",
               LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )
               != LDAP_SUCCESS ) {
                   ldap_perror( ld, "ldap_search_s" );
                   exit( 1 );
           }

           /* step through each entry returned */
           for ( e = ldap_first_entry( ld, res ); e != NULL;
               e = ldap_next_entry( ld, e ) ) {
                   /* print its name */
                   dn = ldap_get_dn( ld, e );
                   printf( "dn: %s\n", dn );
                   free( dn );

                   /* print each attribute */
                   for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
                       a = ldap_next_attribute( ld, e, ptr ) ) {
                           printf( "attribute: %s\n", a );

                           /* print each value */
                           vals = ldap_get_values( ld, e, a );
                           for ( i = 0; vals[i] != NULL; i++ ) {
                                   printf( "value: %s\n", vals[i] );
                           }
                           ldap_value_free( vals );
                   }
           }
           /* free the search results */
           ldap_msgfree( res );

           /* close and free connection resources */
           ldap_unbind( ld );
   }










Expires 4/97                                                   [Page 33]