rfc1823.txt

中、英文RFC文档大全打包下载完全版 .

           #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.

   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.




Howes & Smith                Informational                      [Page 8]

RFC 1823                        LDAP API                     August 1995


   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() returns the LDAP error code  resulting  from the
   modify  operation.   This  code  can  be interpreted by ldap_perror()
   and friends.

   ldap_modify() 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().

4.8.  Modifying the RDN of an entry

   The ldap_modrdn() and ldap_modrdn_s() routines are used to change the
   name of an LDAP entry.

           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 connection handle;

   dn            The name of the entry whose RDN is to be changed;

   newrdn        The new RDN to give the entry;

   deleteoldrdn  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.




Howes & Smith                Informational                      [Page 9]

RFC 1823                        LDAP API                     August 1995


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

   The ldap_modrdn() routine 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().

4.9.  Adding an entry

   ldap_add() and ldap_add_s() are used to add entries to the LDAP
   directory.

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

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

   Parameters are:

   ld    The connection 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().

4.10.  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 );






Howes & Smith                Informational                     [Page 10]

RFC 1823                        LDAP API                     August 1995


   Parameters are:

   ld       The connection 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 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.  Calls for abandoning an operation

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

           int ldap_abandon( LDAP *ld, int msgid );

   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().

6.  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.

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

           int ldap_msgfree( LDAPMessage *res );







Howes & Smith                Informational                     [Page 11]

RFC 1823                        LDAP API                     August 1995


   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;

   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 second
            specifies 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() or ldap_search_s() or ldap_search_st().

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

             LDAP_RES_BIND
             LDAP_RES_SEARCH_ENTRY
             LDAP_RES_SEARCH_RESULT
             LDAP_RES_MODIFY
             LDAP_RES_ADD
             LDAP_RES_DELETE
             LDAP_RES_MODRDN
             LDAP_RES_COMPARE

   ldap_result() returns 0 if the timeout expired and -1 if an error
   occurs, in which case the ld_errno field of the ld structure will be
   set accordingly.

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








Howes & Smith                Informational                     [Page 12]

RFC 1823                        LDAP API                     August 1995


7.  Calls for error handling

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

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

           char *ldap_err2string( int err );

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

   Parameters are:

   ld       The connection handle;

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

   freeit   A boolean parameter indicating whether the res parameter
            should be freed (non-zero) or not (zero);

   err      An LDAP error code, as returned by ldap_result2error() or
            one of the synchronous API operation calls;

   msg      A message to be displayed before the LDAP error message.

   ldap_result2error() is used to convert the LDAP result message
   obtained from ldap_result(), or the res parameter returned by one of
   the synchronous API operation calls, into a numeric LDAP error code.
   It also parses the ld_matched and ld_error portions of the result
   message and puts them into the connection handle information. All the
   synchronous operation routines call ldap_result2error() before
   returning, ensuring that these fields are set correctly. The relevant
   fields in the connection structue are:

   ld_matched In the event of an LDAP_NO_SUCH_OBJECT error return, this
              parameter contains the extent of the DN matched;

   ld_error   This parameter contains the error message sent in the
              result by the LDAP server.

   ld_errno   The LDAP error code indicating the outcome of the
              operation. It is one of the following constants:




Howes & Smith                Informational                     [Page 13]

RFC 1823                        LDAP API                     August 1995


           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_NO_SUCH_ATTRIBUTE
           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_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






Howes & Smith                Informational                     [Page 14]

RFC 1823                        LDAP API                     August 1995


   ldap_err2string() is used to convert a numeric LDAP error code, as
   returned by ldap_result2error() or one of the synchronous API
   operation calls, into an informative NULL-terminated character 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 connection handle, to standard error.

8.  Calls for parsing search entries

   The following calls are used to parse the entries returned by
   ldap_search() and friends. These entries 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
   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.

8.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 in a search result.
   ldap_count_entries() is used to count the number of entries returned.

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

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

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

   Parameters are:

   ld     The connection handle;