Summary: Isode provides a number of APIs which allow integrators and product developers to build components that allow client programs to connect to, query and modify data in the directory.
Distinguished Names
DS_Status DS_String2DN (const char *str_dn, DS_DN **dn_p)
 Convert an LDAPv3 string formatted DN to the API structure. More...
 
DS_Status DS_DN2String (const DS_DN *dn, char **str_p, size_t *len_p)
 Convert a DSAPI DN to the LDAPv3 string representation. More...
 
DS_Status DS_DN2CanonicalString (const DS_DN *dn, char **str_p, size_t *len_p)
 Obtain a canonical string representation of a DSAPI DN. More...
 
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. More...
 
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. More...
 
DS_Status DS_RDN2DN (const DS_AttrList *attr_list, DS_DN **dn_p)
 Convert a set of attributes (an RDN) to a DSAPI DN. More...
 
DS_Status DS_DN_AppendDN (DS_DN *dn, const DS_DN *suffix_dn)
 Append another DN to this DN. More...
 
DS_Status DS_DN_GetParentDN (const DS_DN *dn, const DS_DN **dn_p)
 Return the parent of a DN. More...
 
DS_Status DS_DN_CompareDN (const DS_DN *dn1, const DS_DN *dn2, int *notequal_p)
 Compare two DNs. More...
 
DS_Status DS_DN_OrderCompareDN (const DS_DN *dn1, const DS_DN *dn2, int *result_p)
 Compare two DNs for ordering. More...
 
DS_Status DS_InternalDN2DSDN (const DS_InternalDN *if_dn, DS_DN **dn_p)
 Convert an internal representation of a DN into a DN. More...
 
DS_Status DS_DSDN2InternalDN (const DS_DN *ds_dn, DS_InternalDN **if_dn_p)
 Convert a DN into an internal representation of a DN. More...
 
void DS_InternalDN_Delete (DS_InternalDN *if_dn)
 Free an internal representation of a DN. More...
 
void DS_DN_Delete (DS_DN *dn)
 Free a DN. More...
 
DS_Status DS_DN_Copy (const DS_DN *dn, DS_DN **copy_p)
 Copy a DN. More...
 
void DS_DNList_Delete (DS_DNList *dn_list)
 Free a DN list. More...
 

Detailed Description

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
[in]str_dnLDAP formatted string DN.
[out]dn_pReturned DS_DN. The caller should free this with DS_DN_Delete().
Return values
DS_E_BADDNThe DN could not be parsed as an LDAPv3 string
DS_E_BADPARAMEither str_dn or dn_p was NULL
DS_E_NOERRORA 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
[in]dnTarget DN.
[out]str_pPointer to receive returned string. This string should be freed later by the caller.
[out]len_pLength of string returned (buffer is length of string plus one).
Return values
DS_E_BADDNIf any of the DN couldn't be converted
DS_E_BADPARAMEither dn or str_p or len_p was NULL
DS_E_NOERRORA valid LDAPv3 string is returned
DS_E_NOMEMORYAn internal memory allocation failed
DS_Status DS_DN2CanonicalString ( const DS_DN dn,
char **  str_p,
size_t *  len_p 
)

Obtain a canonical string representation of a DSAPI DN.

The string returned by this function for a given DN will be indentical to that returned for any equivalent DN, even though their string representations may differ. For example, "cn=Babs Jensen" and "cn=BABS JENSEN" represent the same name, and so will have identical canonical representations, even though the values returned by DS_DN2String for these two DNs may not be identical. Callers should not make assumptions about the specific format of strings returned by this function but may safely make comparisons between canonical strings for the purpose of testing DN equality See also DS_DN_GetHashCode.

Parameters
[in]dnTarget DN.
[out]str_pPointer to receive returned string. This string should be freed later by the caller.
[out]len_pLength of string returned (buffer is length of string plus one).
Return values
DS_E_BADDNIf any of the DN couldn't be converted
DS_E_BADPARAMEither dn or str_p or len_p was NULL
DS_E_NOERRORA canonical string is returned
DS_E_NOMEMORYAn internal memory allocation failed
Since
DSAPI_VERSION 2039
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. See also DS_DN2CanonicalString.

Parameters
[in]dnDN.
[out]hash_pPointer to receive returned hash code.
Return values
DS_E_BADDNIf any of the DN couldn't be parsed
DS_E_BADPARAMdn or hash_p was NULL
DS_E_NOERRORA valid hash code has been returned
DS_E_NOMEMORYAn 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
[in]dnTarget distinguished name.
[out]attr_list_pReturned RDN attribute list.
Return values
DS_E_BADPARAMThe dn was NULL
DS_E_NOERRORThe 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
[in]attr_listThe set of attributes to convert (which are copied)
[out]dn_pReturned DN
Return values
DS_E_BADPARAMEither attr_list or dn was NULL, or there are attributes in attr_list which are not single-valued
DS_E_NOERRORThe 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
[in,out]dnDistinguished name.
[in]suffix_dnAppended DN.
Return values
DS_E_BADPARAMEither dn or suffix_dn was NULL
DS_E_NOERRORThe copied DS_DN was returned
DS_E_NOMEMORYAn 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
[in]dnDistinguished name.
[out]dn_pReturned DN (should not be freed)
Return values
DS_E_BADPARAMEither dn or dn_p was NULL
DS_E_NOERRORThe parent DS_DN was returned
DS_E_BADDNdn 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
[in]dn1First DN
[in]dn2Second DN
[out]notequal_pPointer to receive returned comparison result
Return values
DS_E_BADDNEither dn1 or dn2 was invalid
DS_E_BADPARAMEither dn1 or dn2 or notequal_p was NULL
DS_E_NOERRORThe 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
[in]dn1First DN
[in]dn2Second DN
[out]result_pPointer to receive returned comparison result
Return values
DS_E_BADDNEither dn1 or dn2 was invalid
DS_E_BADPARAMEither dn1 or dn2 or result_p was NULL
DS_E_BADATTRSYNTAXThe syntax of one of the RDNs does not support comparison
DS_E_NOERRORThe 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
[in]if_dnInternal representation of the DN
[out]dn_pReturned DS_DN, which the caller should free with DS_DN_Delete()
Return values
DS_E_BADDNIf any of the RDNs couldn't be converted
DS_E_NOERRORA 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
[in]ds_dnDN to convert
[out]if_dn_pReturned internal representation of a DN, which caller should free with DS_InternalDN_Delete()
Return values
DS_E_BADDNIf any of the RDNs couldn't be converted
DS_E_NOERRORA valid DS_InternalDN was returned
void DS_InternalDN_Delete ( DS_InternalDN if_dn)

Free an internal representation of a DN.

Parameters
[in]if_dnDN to free, or NULL.
void DS_DN_Delete ( DS_DN dn)

Free a DN.

Parameters
[in]dnDN 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
[in]dnDN to copy.
[out]copy_pPointer to returned copy.
Return values
DS_E_BADPARAMEither dn or copy_p was NULL
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_NOERRORA valid DS_DN was returned
void DS_DNList_Delete ( DS_DNList dn_list)

Free a DN list.

Parameters
[in]dn_listDNList to free, or NULL.