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.

Functions

const DS_AttrValDS_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_AttrValDS_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

const DS_AttrVal* DS_AttrValList_GetFirst ( const DS_AttrValList value_list)

Get the first attribute in a list.

Parameters
[in]value_listAttribute value list.
Return values
NULLIf there are no attribute values in the list
non-NULLPointer 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
[in]value_listAttribute value list.
[out]count_pPointer to the returned count.
Return values
DS_E_BADPARAMEither value_list or count_p was NULL
DS_E_NOERRORThe count was returned
const DS_AttrVal* DS_AttrValList_GetNext ( const DS_AttrVal value)

Get the next attribute in a list.

Parameters
[in]valueAttribute value in list.
Return values
NULLIf there are no more attribute values in the list
non-NULLPointer 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
[in]valueSource attribute value.
[out]ber_ptr_pPointer to stored BER bytes.
[out]ber_len_pLength of returned BER bytes.
Return values
DS_E_BADPARAMEither value or ber_ptr_p or ber_len_p was NULL
DS_E_NOERRORThe 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
[in]valueSource attribute value.
[out]str_pReturned string pointer.
[out]str_len_pLength of returned string.
Return values
DS_E_BADATTRSYNTAXEither there was no decoder for the attribute, or the attribute is of a syntax which does not have an LDAPv3 string representation.
DS_E_BADATTRTYPEThere was no syntax handler for the attribute
DS_E_BADATTRVALUEThe value couldn't be decoded
DS_E_BADPARAMEither value or str_p or str_len_p was NULL
DS_E_NOERRORThe LDAPv3 string is returned
DS_E_NOMEMORYAn 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
[in]valueSource attribute value.
[out]ir_pReturned 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_BADATTRSYNTAXThere was no decoder for the attribute
DS_E_BADATTRVALUEThe value was invalid for the specified syntax
DS_E_BADPARAMval was NULL
DS_E_NOERRORAn internal representation was returned
DS_E_NOMEMORYAn 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
[in]valueSource attribute value (not deleted)
[in]irInternal representation to be deleted
Return values
DS_E_BADATTRSYNTAXThere was no free routine for the attribute
DS_E_BADPARAMEither val or ir was NULL
DS_E_NOERRORThe 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
[in]valueDS_AttrVal to normalize.
Return values
DS_E_BADPARAMThe value argument was NULL
DS_E_NOERRORThe DS_AttrVal was normalized successfully, or no change was necessary.
DS_E_NOMEMORYAn internal memory allocation failed
Since
DSAPI_VERSION 2021
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]valueDS_AttrVal to convert
[out]copy_pNew DS_AttrVal regenerated from BER
Return values
DS_E_NOERRORThe DS_AttrVal was regenerated successfully
DS_E_BADPARAMAn argument was NULL
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_BADATTRTYPEConversion problem due to attribute type
DS_E_BADATTRVALUEConversion problem due to attribute value
DS_E_BADATTRSYNTAXConversion problem due to attribute syntax
Since
DSAPI_VERSION 2030
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]av1first DS_AttrVal
[in]av2second DS_AttrVal
[out]res_ppointer to result
Return values
DS_E_BADPARAMEither av1, av2 or res_p was NULL
DS_E_BADATTRSYNTAXit was not possible to compare these two values: either they have different syntaxes or the syntax is not one which allows comparisons.
DS_E_NOERRORThe values were compared, and a result written to res_p
DS_E_NOMEMORYAn 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
[in]avDS_AttrVal to copy.
[out]copy_pPointer to returned copy.
Return values
DS_E_BADPARAMEither av or copy_p was NULL
DS_E_NOERRORThe DS_AttrVal was copied
DS_E_NOMEMORYAn internal memory allocation failed
void DS_AttrVal_Delete ( DS_AttrVal av)

Free a DS_AttrVal structure.

Parameters
[in]avDS_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
[in]av_listDS_AttrValList to copy.
[out]copy_pPointer to returned copy.
Return values
DS_E_BADPARAMEither av_list or copy_p was NULL
DS_E_NOERRORThe DS_AttrValList was copied
DS_E_NOMEMORYAn internal memory allocation failed
void DS_AttrValList_Delete ( DS_AttrValList av_list)

Free a DS_AttrValList structure.

Parameters
[in]av_listDS_AttrValList to free.