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

DS_Status DS_Entry_GetNamedAttr (const DS_Entry *entry, const char *type, const DS_Attr **attr_p)
 Get the named attribute from an attribute list. More...
 
DS_Status DS_Entry_GetAttrList (const DS_Entry *entry, const DS_AttrList **attr_list_p)
 Get the entry attribute list. More...
 
DS_Status DS_Entry_GetModList (const DS_Entry *entry, const DS_AttrList **mod_list_p)
 Get the change-entry's modification list. More...
 
DS_Status DS_AttrList_New (DS_AttrList **attrlist_p, const DS_Attr *attr)
 Create a new Attribute list. Initially the list contains a single Attribute. More...
 
DS_Status DS_AttrList_Append (DS_AttrList *attrlist, const DS_Attr *attr)
 Append an attribute to an Attribute list. More...
 
const DS_AttrDS_AttrList_GetFirst (const DS_AttrList *attr_list)
 Get the first attribute in an attribute list. More...
 
const DS_AttrDS_AttrList_GetNext (const DS_Attr *attr)
 Get the next attribute in a list. More...
 
DS_Status DS_Attr_GetTypeName (const DS_Attr *attr, const char **str_p)
 Return the type name of a given attribute. More...
 
DS_Status DS_Attr_GetModType (const DS_Attr *attr, DSModType *type_p)
 Return the modification type of a given attribute. More...
 
DS_Status DS_Attr_GetValueList (const DS_Attr *attr, const DS_AttrValList **val_list_p)
 Get an attribute's value list. More...
 
DS_Status DS_Attr_AddStringValue (DS_Attr *attr, const char *str, size_t len)
 Add a new string value to a DS_Attr. More...
 
DS_Status DS_Attr_AddBERValue (DS_Attr *attr, const unsigned char *ber, size_t len)
 Add a new BER value to a DS_Attr. More...
 
DS_Status DS_Attr_New (const char *name, DS_Attr **attr_p)
 Create a new DS_Attr structure. More...
 
DS_Status DS_Attr_New_AllowUnknown (const char *name, DS_Attr **attr_p)
 Create a new DS_Attr structure, allowing unknown attribute-types. More...
 
DS_Status DS_Attr_IsUnknown (DS_Attr *attr, int *is_unknown_p)
 Check to see if a DS_Attr has an unknown attribute-type. More...
 
DS_Status DS_Attr_Copy (const DS_Attr *attr, DS_Attr **copy_p)
 Copy a DS_Attr structure. More...
 
void DS_Attr_Delete (DS_Attr *attr)
 Free a DS_Attr structure. More...
 
DS_Status DS_AttrList_Copy (const DS_AttrList *attr_list, DS_AttrList **copy_p)
 Copy a DS_AttrList structure. More...
 
void DS_AttrList_Delete (DS_AttrList *attr_list)
 Free a DS_AttrList structure (and all elements). More...
 

Detailed Description

Function Documentation

DS_Status DS_Entry_GetNamedAttr ( const DS_Entry entry,
const char *  type,
const DS_Attr **  attr_p 
)

Get the named attribute from an attribute list.

This works only with normal entries (not change-entries). For known attribute-types, this matches correctly by alias or normal name. For unknown attribute-types it matches only by the name provided.

Parameters
[in]entrySource directory entry (a normal entry).
[in]typeAttribute type name.
[out]attr_pReturn DS_Attr pointer.
Return values
DS_E_BADPARAMEither entry or type or attr_p was NULL, or type was "", or entry is a change-entry.
DS_E_BADATTRTYPEThe type is unknown to the schema, and was not found in the entry.
DS_E_NOTFOUNDThe type is known to the schema, but was not found in the entry.
DS_Status DS_Entry_GetAttrList ( const DS_Entry entry,
const DS_AttrList **  attr_list_p 
)

Get the entry attribute list.

This works only with normal entries (not change-entries).

Parameters
[in]entrySource directory entry (a normal entry, usually).
[out]attr_list_pReturn attribute list (NULL if this is a change-entry)
Return values
DS_E_BADPARAMIf entry was NULL
DS_E_NOERRORThe DS_AttrList was returned
Examples:
async.c, and read.c.
DS_Status DS_Entry_GetModList ( const DS_Entry entry,
const DS_AttrList **  mod_list_p 
)

Get the change-entry's modification list.

This can be used to get the modification list of Modify and Add change-entries.

Parameters
[in]entrySource change-entry.
[out]mod_list_pReturn attribute modification list.
Return values
DS_E_BADPARAMIf entry was NULL or entry isn't a change-entry
DS_E_NOERRORThe DS_AttrList was returned
Since
DSAPI_VERSION 2007
DS_Status DS_AttrList_New ( DS_AttrList **  attrlist_p,
const DS_Attr attr 
)

Create a new Attribute list. Initially the list contains a single Attribute.

Parameters
[out]attrlist_pReturn DS_AttrList pointer.
[in]attran Attribute of which a copy will be made and used as the first element in the list.
Return values
DS_E_NOERRORa new DS_AttrList was created and returned
DS_E_BADPARAMif attr was NULL
DS_E_NOMEMORYan internal memory allocation failed
Since
DSAPI_VERSION 2003
DS_Status DS_AttrList_Append ( DS_AttrList attrlist,
const DS_Attr attr 
)

Append an attribute to an Attribute list.

Parameters
[in,out]attrlistthe Attribute list
[in]attran Attribute to be appended to the list. A copy of the attribute will be made and appended to the list.
Return values
DS_E_NOERRORattr was appended to attrlist
DS_E_BADPARAMif attrlist was NULL or attr was NULL
DS_E_NOMEMORYan internal memory allocation failed
Since
DSAPI_VERSION 2003
const DS_Attr* DS_AttrList_GetFirst ( const DS_AttrList attr_list)

Get the first attribute in an attribute list.

Parameters
[in]attr_listAttribute list.
Return values
NULLIf there are no attributes in the list
non-NULLPointer to the first attribute in the list
Examples:
async.c, and read.c.
const DS_Attr* DS_AttrList_GetNext ( const DS_Attr attr)

Get the next attribute in a list.

Parameters
[in]attrCurrent attribute in list.
Return values
NULLIf there are no more attributes in the list
non-NULLPointer to the next attribute in the list
Examples:
async.c, and read.c.
DS_Status DS_Attr_GetTypeName ( const DS_Attr attr,
const char **  str_p 
)

Return the type name of a given attribute.

The string returned by this function should not be freed as it points to memory fixed and resident within the API layer.

Parameters
[in]attrAttribute pointer
[out]str_pReturned string pointer.
Return values
DS_E_BADPARAMEither attr or str_p was NULL
DS_E_NOERRORA string was returned
Examples:
async.c, and read.c.
DS_Status DS_Attr_GetModType ( const DS_Attr attr,
DSModType type_p 
)

Return the modification type of a given attribute.

If the attribute is a part of a change-entry, then this function returns the modification type: DSModAdd, DSModDelete or DSModReplace.

Parameters
[in]attrAttribute pointer
[out]type_pReturned DSModType.
Return values
DS_E_BADPARAMEither attr or type_p was NULL
DS_E_NOERRORModification type was returned
Since
DSAPI_VERSION 2007
DS_Status DS_Attr_GetValueList ( const DS_Attr attr,
const DS_AttrValList **  val_list_p 
)

Get an attribute's value list.

Parameters
[in]attrSource attribute.
[out]val_list_pReturned list of values. In the case that this is the result of a read or search operation using DS_SVC_OPT_ATTRSONLY, this pointer will be set to NULL, to indicate that no attribute values are present.
Return values
DS_E_BADPARAMEither attr or val_list_p was NULL
DS_E_NOERRORval_list_p now points at the value list.
Examples:
async.c, and read.c.
DS_Status DS_Attr_AddStringValue ( DS_Attr attr,
const char *  str,
size_t  len 
)

Add a new string value to a DS_Attr.

The resulting DS_Attr structure may then be passed into DS_Entry_AddValues(), DS_Entry_DeleteValues(), or DS_Entry_ReplaceValues().

The passed-in value will be copied into the DS_Attr.

Parameters
[in]attrThe DS_Attr being updated
[in]strThe string being added (not necessarily NUL-terminated)
[in]lenThe length of the string being added
Return values
DS_E_BADATTRTYPEThe attribute attr was not recognized
DS_E_BADPARAMEither attr or str was NULL
DS_E_NOERRORThe DS_Attr was updated
DS_E_NOMEMORYAn internal memory allocation failed
Since
DSAPI_VERSION 2000
Examples:
add.c, and modify.c.
DS_Status DS_Attr_AddBERValue ( DS_Attr attr,
const unsigned char *  ber,
size_t  len 
)

Add a new BER value to a DS_Attr.

The resulting DS_Attr structure may then be passed into DS_Entry_AddValues(), DS_Entry_DeleteValues(), or DS_Entry_ReplaceValues().

The passed-in value will be copied into the DS_Attr.

Parameters
[in]attrThe DS_Attr being updated
[in]berThe value being added
[in]lenThe length of the value being added
Return values
DS_E_BADATTRTYPEThe attribute attr was not recognized
DS_E_BADPARAMEither attr or ber was NULL
DS_E_NOERRORThe DS_Attr was updated
DS_E_NOMEMORYAn internal memory allocation failed
Since
DSAPI_VERSION 2000
DS_Status DS_Attr_New ( const char *  name,
DS_Attr **  attr_p 
)

Create a new DS_Attr structure.

Parameters
[in]nameLDAPv3 attribute name, which is copied.
[out]attr_pReturned pointer
Return values
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_NOERRORA DS_Attr was created
Since
DSAPI_VERSION 2000
Examples:
add.c, and modify.c.
DS_Status DS_Attr_New_AllowUnknown ( const char *  name,
DS_Attr **  attr_p 
)

Create a new DS_Attr structure, allowing unknown attribute-types.

Parameters
[in]nameLDAPv3 attribute name, which is copied.
[out]attr_pReturned pointer
Return values
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_NOERRORA DS_Attr was created
Since
DSAPI_VERSION 2018
DS_Status DS_Attr_IsUnknown ( DS_Attr attr,
int *  is_unknown_p 
)

Check to see if a DS_Attr has an unknown attribute-type.

Parameters
[in]attrDS_Attr to check
[out]is_unknown_pIs this unknown? (1 yes, 0 no)
Return values
DS_E_NOERRORSuccess
DS_E_BADPARAMIf attr is NULL or is_unknown_p is NULL
Since
DSAPI_VERSION 2018
DS_Status DS_Attr_Copy ( const DS_Attr attr,
DS_Attr **  copy_p 
)

Copy a DS_Attr structure.

Parameters
[in]attrDS_Attr to copy.
[out]copy_pPointer to returned copy.
Return values
DS_E_BADPARAMEither attr or copy_p was NULL
DS_E_NOERRORA DS_Attr was returned
DS_E_NOMEMORYAn internal memory allocation failed
void DS_Attr_Delete ( DS_Attr attr)

Free a DS_Attr structure.

Parameters
[in]attrDS_Attr to free, or NULL.
Examples:
add.c, and modify.c.
DS_Status DS_AttrList_Copy ( const DS_AttrList attr_list,
DS_AttrList **  copy_p 
)

Copy a DS_AttrList structure.

Parameters
[in]attr_listDS_AttrList to copy.
[out]copy_pPointer to returned copy.
Return values
DS_E_BADPARAMEither attr_list or copy_p was NULL
DS_E_NOERRORA DS_AttrList was returned
DS_E_NOMEMORYAn internal memory allocation failed
void DS_AttrList_Delete ( DS_AttrList attr_list)

Free a DS_AttrList structure (and all elements).

Parameters
[in]attr_listDS_AttrList to free, or NULL.