LDAP  API
 
介绍
这篇文档定义了 LDAP API （C语言版）。它使用方便，功能强大，大致内容有以下几个方面：
简单浏览LDAP模型
应用程序怎样使用API去获取LDAP信息
详细介绍API 调用函数
举例使用API 及部分样本代码
      下面我们分别介绍。
简单浏览LDAP模型
       LDAP 是以client-server 模型为基础的，在此模型中，客户机可以建立与LDAP服务器的连接，从而发送请求，接收应答。
       LDAP的信息模型是基于实体（entry）的，每个实体都代表着某种对象类型的特例。比如组织机构、用户、网络、计算机等。每一种实体又包含有许多属性，每种属性又由它的实体所代表的对象的类型决定。
      实体用树型结构组织再一起，通常根据政治上的,地理学的,和组织的关系进行分类。每一个实体都有唯一的名字通过它的RDN与它的同属实体相连。

三、LDAP API使用浏览
      一个应用使用LDAP API 的一般步骤：
建立与LDAP server的连接。如使用函数调用 ldap_open()等。
核对身份 ldap server 和（或）X.500 DSA,如可以使用ldap_bind().
执行某些LDAP操作，返回某些结果。
最后断开连接。
API的操作可以被同步执行，也可以异步执行。同步的函数调用以_s结尾。例如：同步查找操作可以通过调用ldap_search_s()来完成。异步调用将返回一个result,用来表示操作结果（如，常量LDAP_SUCCESS或者其它错误代码）。异步调用还将返回初始化操作的消息id。异步操作可以通过调用ldap_abandon()而抛弃。
结果和错误信息被作为一个不透明的结构LDAPMessage 返回，函数调用的目的就是分析这一结构，进一步研究被返回的实体和属性等。有时也负责解释这些属性。下面我们将详细介绍API函数调用。

四、  LDAP API函数调用
      这里所有的调用都含有一个“连接手柄”（connection handle）它指向关于每个连接的信息的LDAP结构。许多调用的返回结果都是LDAPMessage结构形式。下面我们会描绘出这些必要的结构。
    1.  建立连接
   ldap_open() 建立一个同 LDAP server的连接。有关定义如下：
               LDAP *ldap_open( char *hostname, int portno );

      参数说明:
      hostname 空格分开的主机名字表或点分开的LDAP server 可以连接到的主机的IP地址串。主机试着依次连接表中列出的每个名字直到某个连接成功时才停止。
      portno   欲连接的TCP端口号。如果省略则为 LDAP_PORT.
   如果连接不能建立，则返回值为NULL。

2.  Authenticating to the directory
       ldap_bind() 和它的同类派生常用来识别目录：         
          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_simple_bind( LDAP *ld, char *dn, char *passwd );
          int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd );
          int ldap_kerberos_bind( LDAP *ld, char *dn );
          int ldap_kerberos_bind_s( LDAP *ld, char *dn );
 参数说明:
   ld    连接手柄;
   dn    被bind的实体名；
   cred  识别证书；
   method  LDAP_AUTH_SIMPLE, LDAP_AUTH_KRBV41, 或
          LDAP_AUTH_KRBV42, 用以表明要使用的识别方法。
   passwd    为 ldap_simple_bind()而准备的口令,并与实体中的
            userPassword 属性比较。

   3.  Closing the connection
   ldap_unbind() 用来解开同目录的联系并断开建立的连接。
           int ldap_unbind( LDAP *ld );

   参数说明：
      ld   连接手柄；
 通过调用ldap_unbind() ，则ld 连接手柄就无效了。

 
4.  Searching
   ldap_search() 等用来查找 LDAP目录,返回与实体匹配的属性。
           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
           );

参数说明:
   ld        连接手柄;
   base      开始寻找的基础对象的DN
   Scope ：LDAP_SCOPE_BASE,LDAP_SCOPE_ONELEVEL, 或LDAP_SCOPE_SUBTREE，用来表明查找的范围。
filter  ：是一个表示LDAP查询的filter，是字符串表示，它的格式      
       定义在RFC 1588中。
attrs   ：一系列指针字符用于表征查找返回属性
attrsevly：布尔参数：0表示返回属性类型和值；非0，仅返回类型。
timeout   为 ldap_search_st() 而说明当地查找操作的超时值。
res       为同步调用准备的结果参数，记录查找完成的结果。
 在ld连接手柄中有三个域控制查找操作的进行。它们是：
 ld_sizelimit  查找实体实体返回的个数，如果为零，表示无限制。
 ld_timelimit 查找时间限制，如果为零，表示无限制。
 ld_deref   LDAP_DEREF_NEVER,LDAP_DEREF_SEARCHING,
         LDAP_DEREF_FINDING,LDAP_DEREF_ALWAYS之一。
        用来说明再查找中别名怎麽处理。
         LDAP_DEREF_NEVER: 在搜索中或者查找那基础对象时
            做不复引用别名。
          LDAP_DEREF_SEARCHING: 在基础对象的附属的搜索
            中而不是查找那基础对象时做复引用别名。
          LDAP_DEREF_FINDING:  在基础对象而不是其附属的
           搜索中做复引用别名。
           LDAP_DEREF_ALWAYS: 在搜索中或者查找那基础对
            象时做都复引用别名。
         一个异步查找通过调用ldap_search()进行初始化.该操作返
回本初始化查找的消息id，要想得到这个结果，可以调用ldap_result().
     一个同步查找可以调用ldap_search_s() 或 ldap_search_st()来
实现.除了 ldap_search_st() 多了一个参数描述查找时限外，这两个
函数的功能基本是一样的。他们都返回一个查找结果，是LDAP
_SUCCESS 或一些错误信息(看下面的错误处理Error  Handling).
查找操作返回的实体（如果有）必包含一个参数res .这个参数对调
用者来说是不透明的。Entries, attributes, values等等都必须调用下面
的分析程序才能进行分析。包含参数 res 的 结果只有不再使用且调
用 ldap_msgfree()时才被释放掉。

5.  Reading an entry
   LDAP 不直接支持读操作，但此操作可以基于实体的DN的查找来仿效。其参数设置如下：
            scope     LDAP_SCOPE_BASE,
            filter    "(objectclass=*)".
    则attrs 包含有返回的属性表。

6.  Listing the children of an entry
   LDAP 也不直接支持表操作，同上我们有：
           scope      LDAP_SCOPE_ONELEVEL,
           filter    "(objectclass=*)".
     则attrs 就包含了要返回的每个子女实体的属性表。

7.  Modifying an entry
ldap_modify() 和 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     修改表，填入修改方式，如ADD、DELETE等。
  LDAPMod 结构中的域解释如下：
      mod_op        修改操作，它可以是LDAP_MOD_ADD,
            LDAP_MOD_DELETE,或LDAP_MOD_REPLACE.
            这个域也用来表明包含在mod_vals union中的值的类
            型.
   mod_type 被修改的属性的类型。
   mod_vals  需要增加、删除或替换的值。
  ldap_modify_s() 返回的是来自修改操作的LDAP 错误代码，可以
调用ldap_perror()及其一类的函数来解释。
  ldap_modify() 返回的是它对请求初始化的消息 id ，或者是代表错误的值 -1 ，这个操作结果可以通过调用 ldap_result()来获得。
Modifying the RDN of an entry
   ldap_modrdn()和 ldap_modrdn_s() 常用来改变LDAP 实体的名字。
            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  是一个布尔值；用来控制旧的RDN属性值是作为表的某一属性保存下来（0），还是把它删掉（非0）。
  ldap_modrdn_s() 是同步的，返回一个LDAP 错误代码，表示操作出口。
  ldap_modrdn() 则是异步的，返回的是它对请求初始化的消息 id ，或者是代表错误的值 -1 ，这个操作结果可以通过调用 ldap_result()来获得。

 9.  Adding an entry
   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 两个域应被填上。
注意一点被加实体的父母节点必须已经存在。
     ldap_add_s() 和ldap_add()的区别同上面的解释一样。

10.  Deleting an entry
   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还不支持。
   ldap_delete_s() 和ldap_delete() 与前面的解释雷同。

五、放弃操作的调用
       ldap_abandon() 用于执行放弃操作的命令。
           int ldap_abandon( LDAP *ld, int msgid );
   ldap_abandon() 放弃的操作是由消息 id  msgid确定的. 如果放弃操作成功，则返回值为0,否则为 -1.如果该次调用成功，那麽通过调用ldap_result()，则不返回任何结果。
Calls for obtaining results
   ldap_result() 就是用来获得上次异步初始化操作的结果。ldap_ms
-gfree() 用于释放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      布尔参数，仅对查找结果有意义。如果为零，则查找结
           果（实体）一产生就返回；否则查找结果变化时返回。
   timeout  结果返回的等待时间。如果为 NULL ，则 ldap_result()
           会一直等到结果有效才返回。如果它的值为零则指定为
           一个探询行为。
   res      对 ldap_result()来说,它是包含此次操作结果的参数；对
           ldap_msgfree()来说,它是将被释放的结果链。
  如果完成成功，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结构中的ld_errno 域也相应地被设置。
   ldap_msgfree() 释放被指定为参数res的结果结构并且返回它释放的消息的类型。

七、  Calls for error handling
   下面的调用用来解释其它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 是否被释放（如果没有则
　　　　　它的值为０）;
   err     LDAP的错误代码，如ldap_result2error() 或其它同步API
          的返回；
   msg    显示在LDAP错误信息之前的信息。
         ldap_result2error()用来把 LDAP 结果信息转换为数字的
  LDAP 错误代码，LDAP结果信息可能来自ldap_result(), 也可能
是某个同步API操作调用返回的信息 res。它也用来分析结果信息
中的 ld_matched 和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
           LDAP_NO_MEMORY

       ldap_err2string() 用来转换数字的 LDAP 错误代码为常用的
描述错误的NULL-terminated 字符串，数字的 LDAP 错误代码可能
来自ldap_result2error() ，或者某个同步的API操作调用。它返回一个指向静态数据的指针。
       ldap_perror()用来输出由msg提供的信息， followed
   by an indication of the error contained in the ld_errno field of the
   ld connection handle, to standard error.

八、  Calls for parsing（分析） search entries
     下面的 调用是用来分析由ldap_search()及其友函数返回的实体的。这些实体是不透明的，只有通过调用下面描述的函数才能访问。
      1.  Stepping through a set of entries
          ldap_first_entry() 和 ldap_next_entry() 用来步查搜寻结果中的实体序列。 ldap_count_entries() 用来统计返回的实体个数。
   LDAPMesage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
   LDAPMesage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
       int ldap_count_entries( LDAP *ld, LDAPMessage *res );
参数说明：
   ld     连接手柄；
   res   LDAP 操作结果如ldap_result()或其它同步API操作调用
　　　　　的返回结果；
   entry  在ldap_first_entry() 或ldap_next_entry()之前的调用的返
          回实体。
     ldap_first_entry() 和 ldap_next_entry()如果没有实体返回，就
  返回为NULL 。而在出现错误时，也返回NULL ，这时就要设
  置连接手柄中的ld_errno 来指示这个错误。
ldap_count_entries() 返回包含在实体链中的实体个数，也用来
  统计调用ldap_first_entry() 或 ldap_next_entry()之后，链中剩余的
  实体个数。
     2.  Stepping through the attributes of an entry
       ldap_first_attribute() 和 ldap_next_attribute() 用来步查实体
   返回的属性类型表。
           char *ldap_first_attribute(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   void            **ptr
           );
           char *ldap_next_attribute(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   void            *ptr
           );

参数说明：
   ld     连接手柄；
   entry  被步查属性的实体 ，如ldap_first_entry() 或ldap_next
         _entry()返回的;
   ptr    在 ldap_first_attribute()中,它是内部跟踪实体当前位置的
          指针地址；在ldap_next_attribute()中,它是在ldap_first_
          attribute()之前的调用返回的指针。
   如果到达属性表的底端时，或有错误时，ldap_first_attribute()和
 ldap_next_attribute() 都返回NULL，而在出现错误时就要设置连接
 手柄中的ld_errno 来指示这个错误。
3.  Retrieving the values of an attribute
     ldap_get_values() 和 ldap_get_values_len() 用来恢复给定的实体的属性值。ldap_count_values() 和 ldap_count_values_len() 用来统计返回的值。ldap_value_free() 和 ldap_value_free_len() 用来释放属性值。
           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 );
参数说明：
   ld     连接手柄；
   entry  被恢复属性值的实体 ，如ldap_first_entry() 或ldap_next
         _entry()返回的;
   attr   被恢复值的属性 ，如ldap_first_attribute() 或 ldap_next
         _attribute()返回的; or a caller- supplied string (e.g., "mail");
   vals   在ldap_get_values() 或 ldap_get_values_len()之前的调用
         返回值。
  4.  Retrieving the name of an entry
      ldap_get_dn()用来恢复实体名。ldap_explode_dn()用来把名字
 分开，形成若干部分。ldap_dn2ufn()用来把名字转换成 "user friendly"
 格式。
           char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
           char **ldap_explode_dn( char *dn, int notypes );
           char *ldap_dn2ufn( char *dn );
参数说明：
   ld     连接手柄；
   entry   被恢复名字的实体 ，如ldap_first_entry() 或ldap_next
         _entry()返回的;
   dn      要被分开的 dn ,如 ldap_get_dn()的返回;
   notypes  布尔参数，如果非零，则dn的各成分应该使它们的类
           型信息成条带状（如： "cn=Babs" 应变为 "Babs")。

   五、举例使用API 及部分样本代码

   #include <ldap.h>

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

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

           /* 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: %s0, 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: %s0, a );

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

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