LDAP_GET_DN

Use the LDAP_GET_DN API or LDAP routine to handle DN and RDN routines.

ldap_dn2ufn
ldap_get_dn
ldap_explode_dn
ldap_explode_dns
ldap_explode_rdn

Synopsis

#include ldap.h


char *ldap_dn2ufn(
        const char *dn) 

char *ldap_get_dn(
        LDAP        *ld,
        LDAPMessage *entry)

char **ldap_explode_dn(
         const char *dn,
         int        notypes)

char **ldap_explode_dns(
         const char *dn)

char **ldap_explode_rdn(
         const char *rdn,
         int        notypes)

Input parameters

ld: Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().
dn: Specifies the DN to be exploded (as returned from ldap_get_dn()) or converted to a simple form (as returned from ldap_dn2ufn()).
rdn: Specifies the RDN to be exploded (as returned from ldap_explode_dn()).
entry: Specifies the entry whose dn is to be retrieved.
notypes: Specifies whether type names are to be returned for each RDN. If nonzero, the type information is stripped. If zero, the type information is retained. For example, setting notypes to 1 can result in the RDN cn=Fido being returned as Fido.

Usage

The ldap_dn2ufn() routine takes a DN and converts it into a simple representation by removing the attribute type that is associated with each RDN. For example, the DN cn=John Doe, ou=Widget Division, ou=Austin, o=sample is returned in simple form as John Doe, Widget Division, Austin, sample. Space for the simple name is obtained by the LDAP API, and must be freed by a call to ldap_memfree().

The ldap_get_dn() routine takes an entry as returned by ldap_first_entry() or ldap_next_entry() and returns a copy of the DN entry. Space for the DN is obtained by the LDAP API, and must be freed by a call to ldap_memfree().

The ldap_explode_dn() routine takes a DN (as returned by ldap_get_dn()) and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. The ldap_explode_dn() API returns a NULL-terminated array of character strings, each component of which contains an RDN from the DN. The notypes parameter is used to request that only the RDN values, and not their types, be returned. For example, the DN cn=Bob,c=US returns an array as either {"cn=Bob","c=US",NULL} or {"Bob","US",NULL} depending on whether notypes was 0 or 1. The result can be freed by calling ldap_value_free().

The ldap_explode_dns() routine takes a DNS-style DN and breaks it up into its component parts. It returns a NULL-terminated array of character strings. For example, the DN austin.ibm.com returns { "austin", "ibm", "com", NULL }. The result can be freed by calling ldap_value_free().

The ldap_explode_rdn() routine takes an RDN (as returned by ldap_explode_dn()) and breaks it up into its component parts. The ldap_explode_rdn() API returns a NULL-terminated array of character strings. The notypes parameter is used to request that only the component values be returned, not their types. For example, the RDN "ou=Research + cn=Bob" returns as either {"ou=Research", "cn=Bob", NULL} or {"Research","Bob", NULL}, depending on whether notypes was 0 or 1. The result can be freed by calling ldap_value_free().

The client DN processing functions normalize attribute values that contain compound RDNs, escaped hex representations of UTF-8 characters and ber-encoded values. The functions also check that the DN passed in is in a correct format according to RFC 2253. ldap_explode_rdn removes back slashes (\) from in front of special characters.

ldap_dn2ufn, ldap_explode_dn and ldap_explode_rdn normalize attribute values by doing the following changes:

A back slash followed by a two-digit hex representation of a UTF-8 character is converted to the character representation. For example, cn=\4A\6F\68\6E Doe is converted to cn=John Doe.
A ber-encoded value is converted to a UTF-8 value. For example, cn=#04044A6F686E20446F65 is converted to cn=John Doe.

ldap_dn2ufn, ldap_explode_dn and ldap_explode_rdn check that the DN passed in is valid. If the DN is not valid, NULL is returned. A DN is not valid if the attribute type or value are in invalid formats. For more information, see RFC 2253.

ldap_dn2ufn, ldap_explode_dn, and ldap_explode_rdn handle compound RDNs. For example:

The DN cn=John+sn=Doe passed into ldap_dn2ufn returns John+Doe
ldap_explode_dn with notype returns John+Doe
ldap_explode_rdn with notype returns [0]=John [1]=Doe

ldap_explode_rdn removes the back slash from in front of special characters. For example, when you call ldap_explode_rdn(cn=Doe\<Jane+ou=LDAP+o=sample,1), ldap_explode_rdn returns:

[0] = Doe<Jane
[1] = LDAP
[2] =sample

Errors

If an error occurs in ldap_dn2ufn(), ldap_get_dn(), ldap_explode_dn(), or ldap_explode_rdn(), NULL is returned. If ldap_get_dn() returns NULL, the ldap_get_errno() API can be used to obtain the error code. See LDAP_ERROR for a description of possible error codes.

Notes®

These routines allocate memory that the caller must deallocate.