rfc1823.txt

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

   res    The search result, as obtained by a call to one of the syn-
          chronous 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 exist to be returned. NULL is also returned if an error
   occurs while stepping through the entries, in which case the ld_errno
   field of the ld connection 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



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


   that remain in a chain if called with an entry returned by
   ldap_first_entry() or ldap_next_entry().

8.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,
                   void            **ptr
           );
           char *ldap_next_attribute(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   void            *ptr
           );

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

   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 ld_errno field in the ld connection handle will be
   set to indicate the error.

   Both routines return a pointer to a per-connection buffer containing
   the current attribute name. This should be treated like static data.
   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.

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






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


8.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:

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





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


   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 malloc'ed and should be freed by
   calling either ldap_value_free() or ldap_value_free_len() when no
   longer in use.

8.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_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, as returned by ldap_get_dn();

   notypes A boolean parameter, if non-zero indicating that the dn com-
           ponents 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 ld_errno in the ld connection 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 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_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.



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


9.  Security Considerations

   LDAP supports minimal security during connection authentication.

10.  Acknowledgements

   This material is based upon work supported by the National Science
   Foundation under Grant No. NCR-9416667.

11.  Bibliography

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
















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


12.  Authors' Addresses

       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]





























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


13.  Appendix A - Sample LDAP API Code

   #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 */



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


                           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 );
   }






































Howes & Smith                Informational                     [Page 22]