mirror/openldap
2
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2024-12-21 03:10:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

Make it clear that ldap_explode_dn() and friends are deprecated.

Browse Source
This commit is contained in:
Kurt Zeilenga 2002-06-17 22:45:34 +00:00
parent 9a38d98d37
commit cbaf9f6649
1 changed files with 67 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
doc/man/man3/ldap_get_dn.3
View File

@ -13,6 +13,12 @@ ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling
char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )
.LP
.ft B
int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
.LP
.ft B
int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
.LP
.ft B
char **ldap_explode_dn( const char *dn, int notypes )
.LP
.ft B
@ -29,12 +35,6 @@ char *ldap_dcedn2dn( const char * dn )
.LP
.ft B
char *ldap_dn2ad_canonical( const char * dn )
.LP
.ft B
int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )
.LP
.ft B
int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )
.SH DESCRIPTION
These routines allow LDAP entry names (Distinguished Names, or DNs)
to be obtained, parsed, converted to a user-friendly form, and tested.
@ -53,60 +53,6 @@ the entry's DN. Space for the DN will be obtained dynamically
and should be freed by the caller using
.BR ldap_memfree (3).
.LP
The
.B ldap_explode_dn()
routine takes a DN as returned by
.B ldap_get_dn()
and breaks it up into its component parts. Each part is known as a
Relative Distinguished Name, or RDN.
.B ldap_explode_dn()
returns a
NULL-terminated array, each component of which contains an RDN from the
DN. The \fInotypes\fP parameter is used to request that only the RDN
values be returned, not their types. For example, the DN "cn=Bob,
c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
"US", NULL }, depending on whether notypes was 0 or 1, respectively.
The result can be freed by calling
.BR ldap_value_free (3).
.LP
Similarly, the
.B ldap_explode_rdn()
routine takes an RDN as returned by
.B ldap_explode_dn(dn,0)
and breaks it up into its "type=value" component parts (or just "value",
if the \fInotypes\fP parameter is set). Note the value is not
unescaped. The result can be freed by calling
.BR ldap_value_free (3).
.LP
.B ldap_dn2ufn()
is used to turn a DN as returned by
.BR ldap_get_dn (3)
into a more user-friendly form, stripping off all type names. See
"Using the Directory to Achieve User Friendly Naming" (RFC 1781)
for more details on the UFN format. Due to the ambigious nature
of the format, it is generally only used for display purposes.
The space for the UFN returned is obtained dynamically and the user
is responsible for freeing it via a call to
.BR ldap_memfree (3).
.LP
.B ldap_dn2dcedn()
is used to turn a DN as returned by
.BR ldap_get_dn (3)
into a DCE-style DN, e.g. a string with most-significant to least
significant rdns separated by slashes ('/'); rdn components
are separated by commas (',').
Only printable chars (e.g. LDAPv2 printable string) are allowed,
at least in this implementation.
.B ldap_dcedn2dn()
performs the opposite operation.
.B ldap_dn2ad_canonical()
turns a DN into a AD canonical name, which is basically a DCE dn
with attribute types omitted.
The trailing domain, if present, is turned in a DNS-like domain.
The space for the returned value is obtained dynamically and the user
is responsible for freeing it via a call to
.BR ldap_memfree (3).
.LP
.B ldap_str2dn()
parses a string representation of a distinguished name contained in
.B str
@ -198,6 +144,67 @@ plus
.fi
for user-friendly naming (RFC 1781) and AD canonical.
.LP
The following routines are viewed as deprecated in favor of
.B ldap_str2dn()
and
.BR ldap_dn2str().
They are provided to support legacy applications.
.LP
The
.B ldap_explode_dn()
routine takes a DN as returned by
.B ldap_get_dn()
and breaks it up into its component parts. Each part is known as a
Relative Distinguished Name, or RDN.
.B ldap_explode_dn()
returns a
NULL-terminated array, each component of which contains an RDN from the
DN. The \fInotypes\fP parameter is used to request that only the RDN
values be returned, not their types. For example, the DN "cn=Bob,
c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob",
"US", NULL }, depending on whether notypes was 0 or 1, respectively.
Assertion values in RDN strings may included escaped characters.
The result can be freed by calling
.BR ldap_value_free (3).
.LP
Similarly, the
.B ldap_explode_rdn()
routine takes an RDN as returned by
.B ldap_explode_dn(dn,0)
and breaks it up into its "type=value" component parts (or just "value",
if the \fInotypes\fP parameter is set). Note the value is not
unescaped. The result can be freed by calling
.BR ldap_value_free (3).
.LP
.B ldap_dn2ufn()
is used to turn a DN as returned by
.BR ldap_get_dn (3)
into a more user-friendly form, stripping off all type names. See
"Using the Directory to Achieve User Friendly Naming" (RFC 1781)
for more details on the UFN format. Due to the ambigious nature
of the format, it is generally only used for display purposes.
The space for the UFN returned is obtained dynamically and the user
is responsible for freeing it via a call to
.BR ldap_memfree (3).
.LP
.B ldap_dn2dcedn()
is used to turn a DN as returned by
.BR ldap_get_dn (3)
into a DCE-style DN, e.g. a string with most-significant to least
significant rdns separated by slashes ('/'); rdn components
are separated by commas (',').
Only printable chars (e.g. LDAPv2 printable string) are allowed,
at least in this implementation.
.B ldap_dcedn2dn()
performs the opposite operation.
.B ldap_dn2ad_canonical()
turns a DN into a AD canonical name, which is basically a DCE dn
with attribute types omitted.
The trailing domain, if present, is turned in a DNS-like domain.
The space for the returned value is obtained dynamically and the user
is responsible for freeing it via a call to
.BR ldap_memfree (3).
.SH ERRORS
If an error occurs in
.BR ldap_get_dn() ,