Functions
const DS_AttrVal *	DS_AttrValList_GetFirst (const DS_AttrValList *value_list)
	Get the first attribute in a list. More...

DS_Status	DS_AttrValList_GetCount (const DS_AttrValList value_list, int count_p)
	Count the attribute values in a list. More...

const DS_AttrVal *	DS_AttrValList_GetNext (const DS_AttrVal *value)
	Get the next attribute in a list. More...

DS_Status	DS_AttrVal_GetBERPointer (const DS_AttrVal value, const unsigned char ber_ptr_p, size_t ber_len_p)
	Return a pointer to the stored BER encoding. More...

DS_Status	DS_AttrVal_GetStringPointer (const DS_AttrVal value, const char str_p, size_t str_len_p)
	Return a pointer to the stored LDAPv3 format string encoding. More...

DS_Status	DS_AttrVal_GetInternal (const DS_AttrVal value, const void *ir_p)
	Verify that the contents of a DS_AttrVal have a valid internal representation, and optionally return a pointer to the internal representation of the value. More...

DS_Status	DS_AttrVal_Internal_Delete (const DS_AttrVal value, void ir)
	Delete a pointer to the internal representation of a value. More...

DS_Status	DS_AttrVal_Normalize (const DS_AttrVal *value)
	Normalize the value in a DS_AttrVal. More...

DS_Status	DS_AttrVal_RegenerateBER (const DS_AttrVal value, DS_AttrVal *copy_p)
	Regenerate the attribute value via BER. More...

DS_Status	DS_AttrVal_Compare (const DS_AttrVal av1, const DS_AttrVal av2, int *res_p)
	Compare two DS_AttrVal values. More...

DS_Status	DS_AttrVal_Copy (const DS_AttrVal av, DS_AttrVal *copy_p)
	Copy a DS_AttrVal structure. More...

void	DS_AttrVal_Delete (DS_AttrVal *av)
	Free a DS_AttrVal structure. More...

DS_Status	DS_AttrValList_Copy (const DS_AttrValList av_list, DS_AttrValList *copy_p)
	Copy a DS_AttrValList structure. More...

void	DS_AttrValList_Delete (DS_AttrValList *av_list)
	Free a DS_AttrValList structure. More...

Detailed Description

Function Documentation

◆ DS_AttrValList_GetFirst()

const DS_AttrVal* DS_AttrValList_GetFirst ( const DS_AttrValList * value_list )

Get the first attribute in a list.

Parameters

[in] value_list Attribute value list.

Return values

NULL	If there are no attribute values in the list
non-NULL	Pointer to the first attribute value in the list

Examples:: async.c, and read.c.

◆ DS_AttrValList_GetCount()

DS_Status DS_AttrValList_GetCount	(	const DS_AttrValList *	value_list,
		int *	count_p
	)

Count the attribute values in a list.

Parameters

[in]	value_list	Attribute value list.
[out]	count_p	Pointer to the returned count.

Return values

DS_E_BADPARAM	Either value_list or count_p was NULL
DS_E_NOERROR	The count was returned

◆ DS_AttrValList_GetNext()

const DS_AttrVal* DS_AttrValList_GetNext ( const DS_AttrVal * value )

Get the next attribute in a list.

Parameters

[in] value Attribute value in list.

Return values

NULL	If there are no more attribute values in the list
non-NULL	Pointer to the next attribute value in the list

Examples:: async.c, and read.c.

◆ DS_AttrVal_GetBERPointer()

DS_Status DS_AttrVal_GetBERPointer	(	const DS_AttrVal *	value,
		const unsigned char **	ber_ptr_p,
		size_t *	ber_len_p
	)

Return a pointer to the stored BER encoding.

The contents of the referenced memory should not be modified by the caller.

Parameters

[in]	value	Source attribute value.
[out]	ber_ptr_p	Pointer to stored BER bytes.
[out]	ber_len_p	Length of returned BER bytes.

Return values

DS_E_BADPARAM	Either value or ber_ptr_p or ber_len_p was NULL
DS_E_NOERROR	The BER value was returned

◆ DS_AttrVal_GetStringPointer()

DS_Status DS_AttrVal_GetStringPointer	(	const DS_AttrVal *	value,
		const char **	str_p,
		size_t *	str_len_p
	)

Return a pointer to the stored LDAPv3 format string encoding.

The contents of this memory should not be modified by the caller. Note that some attribute types do not have a corresponding LDAPv3 string format. In such cases the procedure will return an error.

The returned string is NUL terminated. The returned length does not take account of the terminating NUL.

Parameters

[in]	value	Source attribute value.
[out]	str_p	Returned string pointer.
[out]	str_len_p	Length of returned string.

Return values

DS_E_BADATTRSYNTAX	Either there was no decoder for the attribute, or the attribute is of a syntax which does not have an LDAPv3 string representation.
DS_E_BADATTRTYPE	There was no syntax handler for the attribute
DS_E_BADATTRVALUE	The value couldn't be decoded
DS_E_BADPARAM	Either value or str_p or str_len_p was NULL
DS_E_NOERROR	The LDAPv3 string is returned
DS_E_NOMEMORY	An internal memory allocation failed

Examples:: async.c, and read.c.

◆ DS_AttrVal_GetInternal()

DS_Status DS_AttrVal_GetInternal	(	const DS_AttrVal *	value,
		const void **	ir_p
	)

Verify that the contents of a DS_AttrVal have a valid internal representation, and optionally return a pointer to the internal representation of the value.

If a pointer is returned, then it needs to be cast by the caller into the appropriate type, and freed by the caller using DS_AttrVal_Internal_Delete().

Parameters

[in]	value	Source attribute value.
[out]	ir_p	Returned pointer to internal representation. This may be NULL, in which case the return status of the function indicates whether the value contained in val was valid.

Return values

DS_E_BADATTRSYNTAX	There was no decoder for the attribute
DS_E_BADATTRVALUE	The value was invalid for the specified syntax
DS_E_BADPARAM	val was NULL
DS_E_NOERROR	An internal representation was returned
DS_E_NOMEMORY	An internal memory allocation failed

◆ DS_AttrVal_Internal_Delete()

DS_Status DS_AttrVal_Internal_Delete	(	const DS_AttrVal *	value,
		void *	ir
	)

Delete a pointer to the internal representation of a value.

Parameters

[in]	value	Source attribute value (not deleted)
[in]	ir	Internal representation to be deleted

Return values

DS_E_BADATTRSYNTAX	There was no free routine for the attribute
DS_E_BADPARAM	Either val or ir was NULL
DS_E_NOERROR	The memory was freed

◆ DS_AttrVal_Normalize()

DS_Status DS_AttrVal_Normalize ( const DS_AttrVal * value )

Normalize the value in a DS_AttrVal.

Parse the string value of the attribute to the internal format and then convert back to a string, replacing the original value. This has the effect of normalizing the string to the preferred format. Binary values (JPEG, etc) and BER values are left untouched.

For example: this can be used to convert OR-Addresses from F.401 format to the normal format, it strips unnecessary spaces out of DNs and corrects the case of their c=/cn= tags, and it corrects the case of objectclass names.

Parameters

[in] value DS_AttrVal to normalize.

Return values

DS_E_BADPARAM	The value argument was NULL
DS_E_NOERROR	The DS_AttrVal was normalized successfully, or no change was necessary.
DS_E_NOMEMORY	An internal memory allocation failed

Since: DSAPI_VERSION 2021

◆ DS_AttrVal_RegenerateBER()

DS_Status DS_AttrVal_RegenerateBER	(	const DS_AttrVal *	value,
		DS_AttrVal **	copy_p
	)

Regenerate the attribute value via BER.

Convert the given attribute value to BER and then create a new attribute value from the BER value. This allows access to the BER representation even for values that have been created from strings or that have come from an LDAP or LDIF source.

Parameters

[in]	value	DS_AttrVal to convert
[out]	copy_p	New DS_AttrVal regenerated from BER

Return values

DS_E_NOERROR	The DS_AttrVal was regenerated successfully
DS_E_BADPARAM	An argument was NULL
DS_E_NOMEMORY	An internal memory allocation failed
DS_E_BADATTRTYPE	Conversion problem due to attribute type
DS_E_BADATTRVALUE	Conversion problem due to attribute value
DS_E_BADATTRSYNTAX	Conversion problem due to attribute syntax

Since: DSAPI_VERSION 2030

◆ DS_AttrVal_Compare()

DS_Status DS_AttrVal_Compare	(	const DS_AttrVal *	av1,
		const DS_AttrVal *	av2,
		int *	res_p
	)

Compare two DS_AttrVal values.

The two values are compared, using a syntax-specific comparison function. The result of the comparison will be -1, 0 or 1 depending on whether av1 is "less than", "equal to" or "greater than" av2.

Parameters

[in]	av1	first DS_AttrVal
[in]	av2	second DS_AttrVal
[out]	res_p	pointer to result

Return values

DS_E_BADPARAM	Either av1, av2 or res_p was NULL
DS_E_BADATTRSYNTAX	it was not possible to compare these two values: either they have different syntaxes or the syntax is not one which allows comparisons.
DS_E_NOERROR	The values were compared, and a result written to res_p
DS_E_NOMEMORY	An internal memory allocation failed

Since: DSAPI_VERSION 2028

◆ DS_AttrVal_Copy()

DS_Status DS_AttrVal_Copy	(	const DS_AttrVal *	av,
		DS_AttrVal **	copy_p
	)

Copy a DS_AttrVal structure.

Parameters

[in]	av	DS_AttrVal to copy.
[out]	copy_p	Pointer to returned copy.

Return values

DS_E_BADPARAM	Either av or copy_p was NULL
DS_E_NOERROR	The DS_AttrVal was copied
DS_E_NOMEMORY	An internal memory allocation failed

◆ DS_AttrVal_Delete()

void DS_AttrVal_Delete ( DS_AttrVal * av )

Free a DS_AttrVal structure.

Parameters

[in] av DS_AttrVal to free, or NULL.

◆ DS_AttrValList_Copy()

DS_Status DS_AttrValList_Copy	(	const DS_AttrValList *	av_list,
		DS_AttrValList **	copy_p
	)

Copy a DS_AttrValList structure.

Parameters

[in]	av_list	DS_AttrValList to copy.
[out]	copy_p	Pointer to returned copy.

Return values

DS_E_BADPARAM	Either av_list or copy_p was NULL
DS_E_NOERROR	The DS_AttrValList was copied
DS_E_NOMEMORY	An internal memory allocation failed

◆ DS_AttrValList_Delete()

void DS_AttrValList_Delete ( DS_AttrValList * av_list )

Free a DS_AttrValList structure.

Parameters

[in] av_list DS_AttrValList to free.

Directory Client API

Functions

Detailed Description

Function Documentation

◆ DS_AttrValList_GetFirst()

◆ DS_AttrValList_GetCount()

◆ DS_AttrValList_GetNext()

◆ DS_AttrVal_GetBERPointer()

◆ DS_AttrVal_GetStringPointer()

◆ DS_AttrVal_GetInternal()

◆ DS_AttrVal_Internal_Delete()

◆ DS_AttrVal_Normalize()

◆ DS_AttrVal_RegenerateBER()

◆ DS_AttrVal_Compare()

◆ DS_AttrVal_Copy()

◆ DS_AttrVal_Delete()

◆ DS_AttrValList_Copy()

◆ DS_AttrValList_Delete()