rfc1823.txt

最近的中文RFC文档

           LDAP_NO_MEMORY

   ldap_err2string()用于将数字型的LDAP出错代码（例如ldap_result2error()的返回值，或
任意一同步API操作调用结果）转换为描述该出错信息的字符串。其返回一个指向静态数
据的指针。
   ldap_perror() 用于将ld_errno域中参数msg中包含的信息转换为标准的错误信息。
8.  对查询结果的处理
   下面的函数调用用于分析由ldap_search()及其友员函数返回的结果。这些返回值存放在
一个不透明的结构中，只能通过调用下面这些函数来获得。这些函数可用于处理返回的条目、
条目属性、获得条目名称，以及获得条目中给定属性的属性值。
8.1.  条目结果的处理
   函数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_result()获得；

   entry  函数调用ldap_first_entry()或ldap_next_entry()的返回值；

      当没有条目存在时ldap_first_entry()和ldap_next_entry()将返回NULL。当函数在运行
过程中出错时也会返回NULL，但此时ld连接句柄中的ld_errno域将记录该错误信息。
      ldap_count_entries() 返回在条目链中条目的个数。该函数也可被用于计算在函数调用
ldap_first_entry()或ldap_next_entry()中符合条件的条目的个数。
8.2.  对属性结果的处理
   函数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句柄中的ld_errno 域将被设置为error。
      两个进程都将返回一个指向包含当前属性名的联接缓冲的指针。这将被当作静态数据
对待。ldap_first_attribute()将定位并返回一个指向BerElement类型的名为ptr的指针，以
保存当前位置的路径。该指针将被后面的调用ldap_next_attribute() 所引用，以获得下一
个条目的属性结果。
      返回的属性名将被ldap_get_values()极其成员函数利用，以获得相关的属性值。
8.3.  获得属性值
   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()或一个字符串调用的
返回值（例如，"mail"）；

   vals   先前调用ldap_get_values()或ldap_get_values_len()的返回值。

   两种不同形式的调用都是有条件的。第一重形式只适用于非二进制的字符串类型数据；
第二种_len形式适用于任何形式的数据。

   注意，返回的值当不再使用时，应调用函数ldap_value_free()或ldap_value_free_len()进行
释放。
8.4.  目录项DN分析处理
   ldap_get_dn() 用于获得条目的dn 。

   ldap_explode_dn() 用于将 dn 中的各字段切开。

 ldap_dn2ufn()  用于将dn 的名字转换成较易读取的名字。

           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      可由ldap_get_dn()的返回值得到；

   notypes  布尔型参数，如果非零表明dn的组成部分将只包含属性值，而不包含属性名。         
(例如，"cn=Babs"将变为"Babs")。

   ldap_get_dn() 当dn分析错误时返回NULL，为ld连接句柄设置ld_errno以指明错误。
它返回一个指向预分配空间的指针，当此空间不再被使用时，调用free() 进行空间释放。这
些DN的返回格式在[4]中有所描述。

   ldap_explode_dn() 返回一个指针数组，该数组包含提供给DN的RDN部分。并通过
notypes参数标识是否包含类型。当不再使用该数组返回值时，可调用ldap_value_free()进行
资源释放。

   ldap_dn2ufn() 将DN转换成较易读取的名字(User Friendly Name)，描述参见[5]。UFN将
返回值到预分配的空间，当此空间不再使用时，可调用free() 函数释放。
9.  安全考虑
   LDAP支持联结鉴别时的少量安全。
10.  鸣谢
   这篇材料基于国家科学中心授权的No. NCR-9416667的大力支持。
11.  参考书目
   [1] The Directory: Selected Attribute Syntaxes.  CCITT,
       Recommendation X.520.

   [2] Howes, T., Kille, S., Yeong, W., and C. Robbins, "The String
       Representation of Standard Attribute Syntaxes", University of
       Michigan, ISODE Consortium, Performance Systems International,
       NeXor Ltd., RFC 1778, March 1995.

   [3] Howes, T., "A String Representation of LDAP Search Filters", RFC
       1558, University of Michigan, December 1993.

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

   [5] Kille, S., "Using the OSI Directory to Achieve User Friendly
       Naming",  RFC 1781, ISODE Consortium, March 1995.

   [6] S.P. Miller, B.C. Neuman, J.I. Schiller, J.H. Saltzer, "Kerberos
       Authentication and Authorization System", MIT Project Athena
       Documentation Section  E.2.1, December 1987

   [7] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access
       Protocol," RFC 1777, Performance Systems International,
       University of Michigan, ISODE Consortium, March 1995.
12.  作者地址
       Tim Howes
       University of Michigan
       ITD Research Systems
       535 W William St.
       Ann Arbor, MI 48103-4943
       USA

       Phone: [phone]
       EMail: [e-mail]

       Mark Smith
       University of Michigan
       ITD Research Systems
       535 W William St.
       Ann Arbor, MI 48103-4943
       USA

       Phone: [phone]
       EMail: [e-mail]
13.  附： 一个简单的LDAP API代码
   #include <ldap.h>

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

           /* 打开一个连接 */
           if ( (ld = ldap_open( "dotted.host.name", LDAP_PORT ))
                   == NULL )
                   exit( 1 );

           /* 匿名登陆 */
           if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
                   ldap_perror( ld, "ldap_simple_bind_s" );
                   exit( 1 );
           }

           /* 查询cn="Babs Jensen"的条目,并返回所有属性 */
           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 );
           }

           /* 分析每个返回的条目 */
           for ( e = ldap_first_entry( ld, res ); e != NULL;
               e = ldap_next_entry( ld, e ) ) {
                   /* 打印对象的dn */
                   dn = ldap_get_dn( ld, e );
                   printf( "dn: %s0, dn );
                   free( dn );

                   /* 打印每个属性 */
                   for ( a = ldap_first_attribute( ld, e, &ptr );
                           a != NULL;
                       a = ldap_next_attribute( ld, e, ptr ) ) {
                           printf( "attribute: %s0, a );

                           /* 打印每个属性值 */

                           vals = ldap_get_values( ld, e, a );
                           for ( i = 0; vals[i] != NULL; i++ ) {
                                   printf( "value: %s0, vals[i] );
                           }
                           ldap_value_free( vals );
                   }
           }
           /* 释放查询结果 */
           ldap_msgfree( res );

           /* 关闭资源连接 */
           ldap_unbind( ld );
   }

RFC1823——The LDAP Application Program Interface         LDAP应用程序接口


19
RFC文档中文翻译计划