Section Contents

 

 

Distinguished Names
[Handling Directory Data]

DS_Status DS_String2DN (const char *str_dn, DS_DN **dn_p)
 Convert an LDAPv3 string formatted DN to the API structure.
DS_Status DS_DN2String (const DS_DN *dn, char **str_p, size_t *len_p)
 Convert a DSAPI DN to the LDAPv3 string representation.
DS_Status DS_DN_GetHashCode (const DS_DN *dn, unsigned int *hash_p)
 Derive a hash code based on the canonical representation of the target DSAPI DN.
DS_Status DS_DN_GetRDN (const DS_DN *dn, const DS_AttrList **attr_list_p)
 Return the RDN (a set of attributes) of the given directory name.
DS_Status DS_RDN2DN (const DS_AttrList *attr_list, DS_DN **dn_p)
 Convert a set of attributes (an RDN) to a DSAPI DN.
DS_Status DS_DN_AppendDN (DS_DN *dn, const DS_DN *suffix_dn)
 Append another DN to this DN.
DS_Status DS_DN_GetParentDN (const DS_DN *dn, const DS_DN **dn_p)
 Return the parent of a DN.
DS_Status DS_DN_CompareDN (const DS_DN *dn1, const DS_DN *dn2, int *notequal_p)
 Compare two DNs.
DS_Status DS_DN_OrderCompareDN (const DS_DN *dn1, const DS_DN *dn2, int *result_p)
 Compare two DNs for ordering.
DS_Status DS_InternalDN2DSDN (const DS_InternalDN *if_dn, DS_DN **dn_p)
 Convert an internal representation of a DN into a DN.
DS_Status DS_DSDN2InternalDN (const DS_DN *ds_dn, DS_InternalDN **if_dn_p)
 Convert a DN into an internal representation of a DN.
void DS_InternalDN_Delete (DS_InternalDN *if_dn)
 Free an internal representation of a DN.
void DS_DN_Delete (DS_DN *dn)
 Free a DN.
DS_Status DS_DN_Copy (const DS_DN *dn, DS_DN **copy_p)
 Copy a DN.
void DS_DNList_Delete (DS_DNList *dn_list)
 Free a DN list.

Function Documentation

DS_Status DS_String2DN ( const char *  str_dn,
DS_DN **  dn_p 
)

Convert an LDAPv3 string formatted DN to the API structure.

Parameters:
str_dn [in] LDAP formatted string DN.
dn_p [out] Returned DS_DN. The caller should free this with DS_DN_Delete().
Return values:
DS_E_BADDN The DN could not be parsed as an LDAPv3 string
DS_E_BADPARAM Either str_dn or dn_p was NULL
DS_E_NOERROR A valid DS_DN is returned
Examples:
add.c, async.c, delete.c, modify.c, read.c, and simple.c.

DS_Status DS_DN2String ( const DS_DN *  dn,
char **  str_p,
size_t *  len_p 
)

Convert a DSAPI DN to the LDAPv3 string representation.

Parameters:
dn [in] Target DN.
str_p [out] Pointer to receive returned string. This string should be freed later by the caller.
len_p [out] Length of string returned (buffer is length of string plus one).
Return values:
DS_E_BADDN If any of the DN couldn't be converted
DS_E_BADPARAM Either dn or str_p or len_p was NULL
DS_E_NOERROR A valid LDAPv3 string is returned
DS_E_NOMEMORY An internal memory allocation failed

DS_Status DS_DN_GetHashCode ( const DS_DN *  dn,
unsigned int *  hash_p 
)

Derive a hash code based on the canonical representation of the target DSAPI DN.

The hash code will be identical for any DNs that have the same canonical value, regardless of their string representation. So, for example, the DNs "cn=Babs Jensen" and "CN=BABS JENSEN" have the same hash code. Note that it is possible that two distinct DNs may have the same hash code: in other words, applications may safely assume that two DS_DNs that have different hash codes represent different DNs, but not that two DS_DNs with the same hash code represent the same DN.

Parameters:
dn [in] DN.
hash_p [out] Pointer to receive returned hash code.
Return values:
DS_E_BADDN If any of the DN couldn't be parsed
DS_E_BADPARAM dn or hash_p was NULL
DS_E_NOERROR A valid hash code has been returned
DS_E_NOMEMORY An internal memory allocation failed
Since:
DSAPI_VERSION 2019

DS_Status DS_DN_GetRDN ( const DS_DN *  dn,
const DS_AttrList **  attr_list_p 
)

Return the RDN (a set of attributes) of the given directory name.

Parameters:
dn [in] Target distinguished name.
attr_list_p [out] Returned RDN attribute list.
Return values:
DS_E_BADPARAM The dn was NULL
DS_E_NOERROR The DS_AttrList comprising the RDN is returned

DS_Status DS_RDN2DN ( const DS_AttrList *  attr_list,
DS_DN **  dn_p 
)

Convert a set of attributes (an RDN) to a DSAPI DN.

Parameters:
attr_list [in] The set of attributes to convert (which are copied)
dn_p [out] Returned DN
Return values:
DS_E_BADPARAM Either attr_list or dn was NULL
DS_E_NOERROR The new DN is returned
Since:
DSAPI_VERSION 2000

DS_Status DS_DN_AppendDN ( DS_DN *  dn,
const DS_DN *  suffix_dn 
)

Append another DN to this DN.

dn becomes the least significant part of the new dn, so for example the result of calling this function and specifying dn as "cn=babs" and suffix_dn is "o=acme", is to modify dn to become "cn=babs, o=acme" (in other words, "Append" refers to the order of the DNs as they will appear in an LDAP String representation).

Parameters:
dn [in,out] Distinguished name.
suffix_dn [in] Appended DN.
Return values:
DS_E_BADPARAM Either dn or suffix_dn was NULL
DS_E_NOERROR The copied DS_DN was returned
DS_E_NOMEMORY An internal memory allocation failed

DS_Status DS_DN_GetParentDN ( const DS_DN *  dn,
const DS_DN **  dn_p 
)

Return the parent of a DN.

Parameters:
dn [in] Distinguished name.
dn_p [out] Returned DN (should not be freed)
Return values:
DS_E_BADPARAM Either dn or dn_p was NULL
DS_E_NOERROR The parent DS_DN was returned
DS_E_BADDN dn represents the root DN, and so has no parent

DS_Status DS_DN_CompareDN ( const DS_DN *  dn1,
const DS_DN *  dn2,
int *  notequal_p 
)

Compare two DNs.

Parameters:
dn1 [in] First DN
dn2 [in] Second DN
notequal_p [out] Pointer to receive returned comparison result
Return values:
DS_E_BADDN Either dn1 or dn2 was invalid
DS_E_BADPARAM Either dn1 or dn2 or notequal_p was NULL
DS_E_NOERROR The DNs were compared.
Returns:
If the DNs were identical, the value pointed to by notequal_p will be set to 0. Otherwise, the value pointed to by notequal_p will be set to 1.

DS_Status DS_DN_OrderCompareDN ( const DS_DN *  dn1,
const DS_DN *  dn2,
int *  result_p 
)

Compare two DNs for ordering.

Parameters:
dn1 [in] First DN
dn2 [in] Second DN
result_p [out] Pointer to receive returned comparison result
Return values:
DS_E_BADDN Either dn1 or dn2 was invalid
DS_E_BADPARAM Either dn1 or dn2 or result_p was NULL
DS_E_BADATTRSYNTAX The syntax of one of the RDNs does not support comparison
DS_E_NOERROR The DNs were compared.
Returns:
The value pointed to by result_p will be set to 0 if the DNs compare equal, to -1 if dn1 sorts before dn2, and otherwise to 1.
Since:
DSAPI_VERSION 2017

DS_Status DS_InternalDN2DSDN ( const DS_InternalDN *  if_dn,
DS_DN **  dn_p 
)

Convert an internal representation of a DN into a DN.

Parameters:
if_dn [in] Internal representation of the DN
dn_p [out] Returned DS_DN, which the caller should free with DS_DN_Delete()
Return values:
DS_E_BADDN If any of the RDNs couldn't be converted
DS_E_NOERROR A valid DN was returned

DS_Status DS_DSDN2InternalDN ( const DS_DN *  ds_dn,
DS_InternalDN **  if_dn_p 
)

Convert a DN into an internal representation of a DN.

Parameters:
ds_dn [in] DN to convert
if_dn_p [out] Returned internal representation of a DN, which caller should free with DS_InternalDN_Delete()
Return values:
DS_E_BADDN If any of the RDNs couldn't be converted
DS_E_NOERROR A valid DS_InternalDN was returned

void DS_InternalDN_Delete ( DS_InternalDN *  if_dn  ) 

Free an internal representation of a DN.

Parameters:
if_dn [in] DN to free, or NULL.

void DS_DN_Delete ( DS_DN *  dn  ) 

Free a DN.

Parameters:
dn [in] DN to free, or NULL.
Examples:
add.c, delete.c, modify.c, and simple.c.

DS_Status DS_DN_Copy ( const DS_DN *  dn,
DS_DN **  copy_p 
)

Copy a DN.

Parameters:
dn [in] DN to copy.
copy_p [out] Pointer to returned copy.
Return values:
DS_E_BADPARAM Either dn or copy_p was NULL
DS_E_NOMEMORY An internal memory allocation failed
DS_E_NOERROR A valid DS_DN was returned

void DS_DNList_Delete ( DS_DNList *  dn_list  ) 

Free a DN list.

Parameters:
dn_list [in] DNList to free, or NULL.

Copyright © 2008 Isode privacy   feedback Subscribe to our rss newsfeed