Section Contents

 

 

Attribute Values
[Handling Directory Data]


Functions

const DS_AttrVal * DS_AttrValList_GetFirst (const DS_AttrValList *value_list)
 Get the first attribute in a list.
DS_Status DS_AttrValList_GetCount (const DS_AttrValList *value_list, int *count_p)
 Count the attribute values in a list.
const DS_AttrVal * DS_AttrValList_GetNext (const DS_AttrVal *value)
 Get the next attribute in a list.
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.
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.
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.
DS_Status DS_AttrVal_Internal_Delete (const DS_AttrVal *value, void *ir)
 Delete a pointer to the internal representation of a value.
DS_Status DS_AttrVal_Normalize (const DS_AttrVal *value)
 Normalize the value in a DS_AttrVal.
DS_Status DS_AttrVal_Compare (const DS_AttrVal *av1, const DS_AttrVal *av2, int *res_p)
 Compare two DS_AttrVal values.
DS_Status DS_AttrVal_Copy (const DS_AttrVal *av, DS_AttrVal **copy_p)
 Copy a DS_AttrVal structure.
void DS_AttrVal_Delete (DS_AttrVal *av)
 Free a DS_AttrVal structure.
DS_Status DS_AttrValList_Copy (const DS_AttrValList *av_list, DS_AttrValList **copy_p)
 Copy a DS_AttrValList structure.
void DS_AttrValList_Delete (DS_AttrValList *av_list)
 Free a DS_AttrValList structure.

Function Documentation

const DS_AttrVal* DS_AttrValList_GetFirst ( const DS_AttrValList *  value_list  ) 

Get the first attribute in a list.

Parameters:
value_list [in] 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_Status DS_AttrValList_GetCount ( const DS_AttrValList *  value_list,
int *  count_p 
)

Count the attribute values in a list.

Parameters:
value_list [in] Attribute value list.
count_p [out] 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

const DS_AttrVal* DS_AttrValList_GetNext ( const DS_AttrVal *  value  ) 

Get the next attribute in a list.

Parameters:
value [in] 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_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:
value [in] Source attribute value.
ber_ptr_p [out] Pointer to stored BER bytes.
ber_len_p [out] 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_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:
value [in] Source attribute value.
str_p [out] Returned string pointer.
str_len_p [out] 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_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:
value [in] Source attribute value.
ir_p [out] 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_Status DS_AttrVal_Internal_Delete ( const DS_AttrVal *  value,
void *  ir 
)

Delete a pointer to the internal representation of a value.

Parameters:
value [in] Source attribute value (not deleted)
ir [in] 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_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:
value [in] 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_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:
av1 [in] first DS_AttrVal
av2 [in] second DS_AttrVal
res_p [out] 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_Status DS_AttrVal_Copy ( const DS_AttrVal *  av,
DS_AttrVal **  copy_p 
)

Copy a DS_AttrVal structure.

Parameters:
av [in] DS_AttrVal to copy.
copy_p [out] 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

void DS_AttrVal_Delete ( DS_AttrVal *  av  ) 

Free a DS_AttrVal structure.

Parameters:
av [in] DS_AttrVal to free, or NULL.

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

Copy a DS_AttrValList structure.

Parameters:
av_list [in] DS_AttrValList to copy.
copy_p [out] 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

void DS_AttrValList_Delete ( DS_AttrValList *  av_list  ) 

Free a DS_AttrValList structure.

Parameters:
av_list [in] DS_AttrValList to free.

Copyright © 2008 Isode privacy   feedback Subscribe to our rss newsfeed