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

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_dn	LDAP formatted string DN.
[out]	dn_p	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_DN2String()

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]	dn	Target DN.
[out]	str_p	Pointer to receive returned string. This string should be freed later by the caller.
[out]	len_p	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_DN2CanonicalString()

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]	dn	Target DN.
[out]	str_p	Pointer to receive returned string. This string should be freed later by the caller.
[out]	len_p	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 canonical string is returned
DS_E_NOMEMORY	An internal memory allocation failed

Since: DSAPI_VERSION 2039

◆ DS_DN_GetHashCode()

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]	dn	DN.
[out]	hash_p	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_DN_GetRDN()

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]	dn	Target distinguished name.
[out]	attr_list_p	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_RDN2DN()

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_list	The set of attributes to convert (which are copied)
[out]	dn_p	Returned DN

Return values

DS_E_BADPARAM	Either attr_list or dn was NULL, or there are attributes in attr_list which are not single-valued
DS_E_NOERROR	The new DN is returned

Since: DSAPI_VERSION 2000

◆ DS_DN_AppendDN()

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]	dn	Distinguished name.
[in]	suffix_dn	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_DN_GetParentDN()

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

Return the parent of a DN.

Parameters

[in]	dn	Distinguished name.
[out]	dn_p	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_DN_CompareDN()

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

Compare two DNs.

Parameters

[in]	dn1	First DN
[in]	dn2	Second DN
[out]	notequal_p	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_DN_OrderCompareDN()

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

Compare two DNs for ordering.

Parameters

[in]	dn1	First DN
[in]	dn2	Second DN
[out]	result_p	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_InternalDN2DSDN()

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_dn	Internal representation of the DN
[out]	dn_p	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_DSDN2InternalDN()

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_dn	DN to convert
[out]	if_dn_p	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

◆ DS_InternalDN_Delete()

void DS_InternalDN_Delete ( DS_InternalDN * if_dn )

Free an internal representation of a DN.

Parameters

[in] if_dn DN to free, or NULL.

◆ DS_DN_Delete()

void DS_DN_Delete ( DS_DN * dn )

Free a DN.

Parameters

[in] dn DN to free, or NULL.

Examples: add.c, delete.c, modify.c, and simple.c.

◆ DS_DN_Copy()

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

Copy a DN.

Parameters

[in]	dn	DN to copy.
[out]	copy_p	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

◆ DS_DNList_Delete()

void DS_DNList_Delete ( DS_DNList * dn_list )

Free a DN list.

Parameters

[in] dn_list DNList to free, or NULL.