rfc1823.txt

最近的中文RFC文档

4.5.  读取条目
   LDAP 不支持直接的读操作。实际上，查询操作中的操作范围：LDAP_SCOPE_BASE，
匹配条件："(objectclass=*)"都利用到了读操作。参数attrs包含了返回的属性列表。
4.6.  子条目列表
   LDAP 不直接支持列表操作。实际上，查询操作中的操作范围：LDAP_SCOPE_ 
ONELEVEL，匹配条件："(objectclass=*)"也利用到了列表操作。参数attrs包含了返回的所
有子条目的属性列表。
4.7.  修改条目
   函数ldap_modify() and ldap_modify_s()用于修改存在的LDAP条目。

           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[] );

   参数：

   ld       联接句柄；

   dn       要修改的条目名；

   mods     属性修改操作模式；

LDAPMod结构域包含以下信息：

  mod_op   操作类型。其值可能为：LDAP_MOD_ADD, LDAP_MOD_DELETE，或 
LDAP_MOD_REPLACE。该域同时指定了mod_vals单元值的类型。如果
为LDAP_MOD_BVALUES 则选择了mod_bvalues模式。否则，mod_values
定义的模式才有效。

 mod_type  修改的属性类型；

mod_vals  值为：add, delete，或replace。mod_values与mod_bvalues不能共用。只有
在mods_op中指定为LDAP_MOD_BVALUES时才能在这里设为
mod_bvalues值。 mod_values为包含字符串的非空数组，字符串可为
NULL。mod_bvalues为包含berval结构的非空数组，用于包含二进制类型
的值，例如图片。

   LDAP_MOD_ADD模式用于在条目中创建新的属性。LDAP_MOD_DELETE模式用于删
除条目中不再需要的属性。如果是删除操作，那么mod_vals域的值将设为NULL。   
LDAP_MOD_REPLACE模式中，属性值将设置为列表中定义的值。所有模式的运行顺序都
遵循它们排列的先后顺序。

   ldap_modify_s()返回修改操作的LDAP出错代码。该代码能被ldap_perror()及其友元函数
解析。
   ldap_modify() 返回初始化信息的id，出错时返回-1。操作结果通过调用ldap_result()获得。
 4.8.  修改条目的RDN
   ldap_modrdn()和ldap_modrdn_s()用于改变条目的名称。

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

   参数：
   ld            连接句柄；

   dn            RDN将改变的条目名称；

   newrdn        给条目的新RDN；

   deleteoldrdn    布尔值，非0表示旧的RDN 值将被删除，为0表示将继续保留旧的RDN
值。

   ldap_modrdn_s()是同步操作，返回操作结果的LDAP错误代码。

   ldap_modrdn()  为异步函数，返回操作初始化的信息id。如果有误返回-1。通过调用
dap_result()可以获得操作的结果。
4.9.  增加条目
   ldap_add()和ldap_add_s()用于增加LDAP目录中的条目。

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

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

   参数：

   ld    连接句柄；

   dn    新添加条目的名称；

   attrs  条目的属性，采用ldap_modify()中定义的LDAPMod结构。要求输入mod_type与
mod_vals域的值，mod_op域缺省。除非遇到常量LDAP_MOD_BVALUES时, 需要用到相
应的mod_bvalues替代mod_vals。

   注意，新添加条目的父条目必须已经存在。

   ldap_add_s()是同步操作，返回操作结果的LDAP错误代码。
   ldap_add()为异步操作，返回操作初始化的信息id。如果有误返回-1。通过调用dap_result()
可以获得操作的结果。
4.10.  删除条目
   ldap_delete()和ldap_delete_s()用于删除LDAP目录中的条目。

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

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

   参数：

   ld       连接句柄；

   dn       需要删除的条目名称。

   注意，被删除的条目必须是“叶”条目（即，不含有子条目）。LDAP不支持删除带有子
条目的结点。

   ldap_delete_s()  是同步操作，返回操作结果的LDAP错误代码。
   ldap_delete()    是异步操作，返回操作初始化的信息id。如果有误返回-1。通过调用
dap_result()可以获得操作的结果。
5.  取消操作
   ldap_abandon()用于取消进行的操作。

           int ldap_abandon( LDAP *ld, int msgid );

   ldap_abandon()通过信息的id号——msgid取消操作。如果操作成功，返回0；否则，返
回-1。在成功调用ldap_abandon()之后，给定信息id的操作结果将不会有返回值。
6.  结果处理
   ldap_result()用于获得前面调用的异步初始化操作的结果。ldap_msgfree()释放由函数
ldap_result()获得的结果或同步查询进程。

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

           int ldap_msgfree( LDAPMessage *res );

   参数：

   ld       连接句柄；

   msgid    操作结果的信息id。如果希望返回所有的结果，则设为常量LDAP_RES_ANY；

 all       一个布尔型参数，仅对查询结果起作用。如果非0，表明在获取了所有查询结
果后再一并返回；为0，表明查询到一个结果就返回一个结果。

   timeout   等待结果返回的最短时间。为NULL表明没有时间限制。为0表示轮询操作。

   res       在ldap_result()中，该参数将保存操作的结果；在ldap_msgfree()中，该参数用
于释放从ldap_result()或ldap_search_s()或ldap_search_st()获得的结果。
            .

   若上面的操作成功，ldap_result()将通过res参数返回结果的类型。其类型为以下几种：
             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()将返回0；如果出错，将返回-1，同时将出错信息记
录到ld_errno 域。
   ldap_msgfree()释放指向res结构的指针并返回释放信息的类型。 
7.  出错处理
   下面的函数调用用于解释由其它LDAP API产生的出错信息。

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

           char *ldap_err2string( int err );

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

   参数：

   ld       连接句柄；

   res      其它LDAP操作的返回值，即ldap_result()的返回值或其它同步API操作的结果；

   freeit    布尔型参数，指明参数res是否被释放（非0，释放；0，不释放）；

   err      LDAP出错代码，即ldap_result2error()的返回值或其它同步API操作的结果；

   msg      在LDAP出错信息之前显示的信息。

   ldap_result2error()用于将从ldap_result()中获得的LDAP结果，或同步API操作的结果转
换为数字类型的LDAP错误代码。并且分析结果信息中的ld_matched and ld_error部分，将
其放入连接句柄信息中。所有的同步操作进程在返回值之前调用ldap_result2error()，以确保
各个域的正确设置。联接结构中相关的域有：

   ld_matched  用于LDAP_NO_SUCH_OBJECT错误值返回时，该参数限制了匹配的DN
的范围；

   ld_error    该参数保存了LDAP服务器发送出的出错信息；

   ld_errno    LDAP出错代码指出了操作的结果。其值为以下的任意一个：

           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