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.
Directory Entries
DS_Status DS_Entry_GetDN (const DS_Entry *entry, const DS_DN **dn_p)
 Get the DN of the given DS_Entry. More...
 
DS_Status DS_Entry_GetNewDN (const DS_Entry *entry, const DS_DN **dn_p)
 Get the New DN specified in the given DS_Entry. More...
 
DS_Status DS_Entry_GetDeleteOldRDN (const DS_Entry *entry, int *flag_p)
 Get the 'delete old RDN' flag for the given DS_Entry. More...
 
DS_Status DS_Entry_SetDN (DS_Entry *entry, const DS_DN *dn)
 Set the DN of the given DS_Entry. More...
 
DS_Status DS_Entry_SetNewDN (DS_Entry *entry, const DS_DN *new_dn)
 Set the 'new DN' of the given 'ModDN' DS_Entry. More...
 
DS_Status DS_Entry_SetDeleteOldRDN (DS_Entry *entry, int flag)
 Set the 'Delete Old RDN' flag of the given 'ModDN' DS_Entry. More...
 
DS_Status DS_Entry_IsNormal (const DS_Entry *entry)
 Check that this DS_Entry is a normal entry (i.e. not a change-entry). More...
 
DS_Status DS_Entry_IsChange (const DS_Entry *entry)
 Check that this DS_Entry is a change-entry, i.e. one of the types: Modify, Add, Delete or ModDN. More...
 
DS_Status DS_Entry_GetType (const DS_Entry *entry, DSEntryType *type_p)
 Get the type of a DS_Entry. More...
 
DS_Status DS_Entry_Convert (DS_Entry *entry, DSEntryType type)
 Convert a DS_Entry to another type of DS_Entry. More...
 
DS_Status DS_Entry_AddValues (DS_Entry *entry, const DS_Attr *attr)
 Append an add-attribute (with values) change to a DS_Entry. More...
 
DS_Status DS_Entry_DeleteValues (DS_Entry *entry, const DS_Attr *attr)
 Append a delete-attribute or delete-attribute-values change to a DS_Entry. More...
 
DS_Status DS_Entry_ReplaceValues (DS_Entry *entry, const DS_Attr *attr)
 Append a replace-attribute-values change to a DS_Entry. More...
 
const DS_EntryDS_EntryList_GetFirst (const DS_EntryList *entry_list)
 Get the first entry in a list of entries. More...
 
const DS_EntryDS_EntryList_GetNext (const DS_Entry *entry)
 Get the next entry in a list of entries. More...
 
DS_Status DS_Entry_New (DS_Entry **entryp)
 Create a DS_Entry structure for a Modify change-entry. More...
 
DS_Status DS_Entry_NewType (DS_Entry **entryp, DSEntryType type, const DS_DN *dn)
 Create a DS_Entry structure of the given type. More...
 
void DS_Entry_Delete (DS_Entry *entry)
 Free a DS_Entry. More...
 
void DS_EntryList_Delete (DS_EntryList *entry_list)
 Free a DS_Entry list. More...
 
DS_Status DS_Entry_Diff (const DS_Entry *entry1, const DS_Entry *entry2, DS_Entry **change_p)
 Compare two entries and generate a Modify change-entry with the differences. More...
 
DS_Status DS_Entry_Apply (const DS_Entry *entry1, const DS_Entry *change, DS_Entry **entry2_p)
 Apply a Modify or Add change-entry to a normal entry and return the result as a normal entry. More...
 

Detailed Description

Function Documentation

DS_Status DS_Entry_GetDN ( const DS_Entry entry,
const DS_DN **  dn_p 
)

Get the DN of the given DS_Entry.

Parameters
[in]entryTarget entry.
[out]dn_pReturned DN, which caller must not free, or NULL for the root DN (default).
Return values
DS_E_BADPARAMEither entry or dn_p was NULL
DS_E_NOERRORA DS_DN was returned
DS_Status DS_Entry_GetNewDN ( const DS_Entry entry,
const DS_DN **  dn_p 
)

Get the New DN specified in the given DS_Entry.

This call is only valid for ModDN change-entries.

Parameters
[in]entryTarget entry.
[out]dn_pReturned DN, which caller must not free, or NULL for the root DN.
Return values
DS_E_BADPARAMEither entry or dn_p was NULL, or this isn't a ModDN change-entry.
DS_E_NOERRORA DS_DN was returned
Since
DSAPI_VERSION 2014
DS_Status DS_Entry_GetDeleteOldRDN ( const DS_Entry entry,
int *  flag_p 
)

Get the 'delete old RDN' flag for the given DS_Entry.

This call is only valid for ModDN change-entries.

Parameters
[in]entryTarget entry.
[out]flag_pReturned flag value
Return values
DS_E_BADPARAMEither entry or flag_p was NULL, or this isn't a ModDN change-entry.
DS_E_NOERRORThe flag value was returned
Since
DSAPI_VERSION 2014
DS_Status DS_Entry_SetDN ( DS_Entry entry,
const DS_DN dn 
)

Set the DN of the given DS_Entry.

Parameters
[in]entryTarget entry.
[in]dnNew DN, which will be copied.
Return values
DS_E_BADPARAMEither entry or dn was NULL
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_NOERRORThe entry's DN was set
Since
DSAPI_VERSION 2000
Examples:
add.c, and modify.c.
DS_Status DS_Entry_SetNewDN ( DS_Entry entry,
const DS_DN new_dn 
)

Set the 'new DN' of the given 'ModDN' DS_Entry.

Parameters
[in]entryTarget ModDN entry.
[in]new_dnNew DN, which will be copied.
Return values
DS_E_BADPARAMEither entry or new_dn was NULL, or entry is not a ModDN entry
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_NOERRORThe entry's new DN was set
Since
DSAPI_VERSION 2015
DS_Status DS_Entry_SetDeleteOldRDN ( DS_Entry entry,
int  flag 
)

Set the 'Delete Old RDN' flag of the given 'ModDN' DS_Entry.

Parameters
[in]entryTarget ModDN entry.
[in]flag'Delete Old RDN' flag
Return values
DS_E_BADPARAMEither entry was NULL, or it was not a ModDN entry
DS_E_NOERRORThe entry's 'Delete Old RDN' flag was set
Since
DSAPI_VERSION 2015
DS_Status DS_Entry_IsNormal ( const DS_Entry entry)

Check that this DS_Entry is a normal entry (i.e. not a change-entry).

Parameters
[in]entryTarget entry.
Return values
DS_E_BADPARAMEither entry is NULL or entry is a change-entry.
DS_E_NOERRORThe entry passes the check.
Since
DSAPI_VERSION 2007
DS_Status DS_Entry_IsChange ( const DS_Entry entry)

Check that this DS_Entry is a change-entry, i.e. one of the types: Modify, Add, Delete or ModDN.

Parameters
[in]entryTarget entry.
Return values
DS_E_BADPARAMEither entry is NULL or entry is a normal entry.
DS_E_NOERRORThe entry passes the check.
Since
DSAPI_VERSION 2007
DS_Status DS_Entry_GetType ( const DS_Entry entry,
DSEntryType type_p 
)

Get the type of a DS_Entry.

Parameters
[in]entryTarget entry.
[out]type_pType of entry.
Return values
DS_E_BADPARAMentry is NULL
DS_E_NOERRORThe type has been returned.
Since
DSAPI_VERSION 2015
DS_Status DS_Entry_Convert ( DS_Entry entry,
DSEntryType  type 
)

Convert a DS_Entry to another type of DS_Entry.

This can convert a DS_Entry between the three types: DSEntryNormal, DSEntryModify and DSEntryAdd, with the restriction that it is only possible to convert from DSEntryModify to the other two types if the modifications consist only of adds. See DS_Entry_Apply() for doing other conversions from DSEntryModify.

Parameters
[in]entryTarget entry.
[out]typeNew type of entry.
Return values
DS_E_BADPARAMentry is NULL, or the new type is invalid
DS_E_BADENTRYConversion is being attempted from DSEntryModify, but there are replace- or delete-attribute changes in the entry which cannot be converted
DS_E_NOERRORThe conversion is complete
Since
DSAPI_VERSION 2015
DS_Status DS_Entry_AddValues ( DS_Entry entry,
const DS_Attr attr 
)

Append an add-attribute (with values) change to a DS_Entry.

This operation is valid only on Modify or Add change-entries.

Parameters
[in]entryTarget change-entry.
[in]attrThe attribute and values to be added, which will be copied into the entry.
Return values
DS_E_BADPARAMEither entry or attr was NULL, or entry is not of the correct type.
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_NOERRORThe entry was updated.
Since
DSAPI_VERSION 2000
Examples:
add.c, and modify.c.
DS_Status DS_Entry_DeleteValues ( DS_Entry entry,
const DS_Attr attr 
)

Append a delete-attribute or delete-attribute-values change to a DS_Entry.

This operation is valid only on Modify change-entries.

The resulting DS_Entry may be passed to DS_ModifySync(), which will send the changes to the Directory Server, or may be applied to another entry in memory using DS_Entry_Apply().

If the attribute has no values, the effect of the change is to delete the whole attribute. Otherwise, just the listed values will be deleted.

Parameters
[in]entryTarget change-entry.
[in]attrThe attribute and (optional) values to be deleted, which will be copied into the change-entry.
Return values
DS_E_BADPARAMEither entry or attr was NULL, or entry is a normal entry
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_NOERRORThe entry was updated.
Since
DSAPI_VERSION 2000
Examples:
modify.c.
DS_Status DS_Entry_ReplaceValues ( DS_Entry entry,
const DS_Attr attr 
)

Append a replace-attribute-values change to a DS_Entry.

This operation is valid only on Modify change-entries.

The resulting DS_Entry may be passed to DS_ModifySync(), which will send the changes to the Directory Server, or may be applied to another entry in memory using DS_Entry_Apply().

If the attribute has no values, the effect of the change is to delete the whole attribute. Otherwise, all the values will be replaced with the listed values.

Parameters
[in]entryTarget change-entry.
[in]attrThe attribute and (optional) values to be replaced, which will be copied into the entry.
Return values
DS_E_BADPARAMEither entry or attr was NULL, or entry is a normal entry
DS_E_NOMEMORYAn internal memory allocation failed
DS_E_NOERRORThe entry was updated.
Since
DSAPI_VERSION 2000
Examples:
modify.c.
const DS_Entry* DS_EntryList_GetFirst ( const DS_EntryList entry_list)

Get the first entry in a list of entries.

Parameters
[in]entry_listSource entry list.
Return values
NULLIf there are no entries in the list
non-NULLPointer to the first entry in the list
Examples:
async.c, and read.c.
const DS_Entry* DS_EntryList_GetNext ( const DS_Entry entry)

Get the next entry in a list of entries.

Parameters
[in]entryCurrent entry in list.
Return values
NULLIf there are no more entries in the list
non-NULLPointer to the next entry in the list
DS_Status DS_Entry_New ( DS_Entry **  entryp)

Create a DS_Entry structure for a Modify change-entry.

This creates an empty Modify change-entry, without a DN.

Parameters
[out]entrypReturn pointer. The caller should delete this using DS_Entry_Delete().
Return values
DS_E_BADPARAMIf entryp was NULL
DS_E_NOERRORA DS_Entry was returned
DS_E_NOMEMORYA memory allocation failed.
Since
DSAPI_VERSION 2000
Examples:
add.c, and modify.c.
DS_Status DS_Entry_NewType ( DS_Entry **  entryp,
DSEntryType  type,
const DS_DN dn 
)

Create a DS_Entry structure of the given type.

This creates an empty change-entry of the given type, with the given DN if required. For DSEntryRename, the new-DN is left uninitialised as NULL and the 'delete_old_rdn' flag is set to true.

Parameters
[out]entrypReturn pointer. The caller should delete this using DS_Entry_Delete().
[in]typeType of DS_Entry to create
[in]dnNew DN, which will be copied, or NULL if not required
Return values
DS_E_BADPARAMIf entryp was NULL or type is invalid
DS_E_NOERRORA DS_Entry was returned
DS_E_NOMEMORYA memory allocation failed.
Since
DSAPI_VERSION 2015
void DS_Entry_Delete ( DS_Entry entry)

Free a DS_Entry.

Parameters
[in]entryDS_Entry to free, or NULL.
Examples:
add.c, and modify.c.
void DS_EntryList_Delete ( DS_EntryList entry_list)

Free a DS_Entry list.

Parameters
[in]entry_listDS_EntryList to free, or NULL.
DS_Status DS_Entry_Diff ( const DS_Entry entry1,
const DS_Entry entry2,
DS_Entry **  change_p 
)

Compare two entries and generate a Modify change-entry with the differences.

This generates the Modify change-entry which when applied to entry1 would give entry2. The change may be applied to an entry in memory using DS_Entry_Apply(), or applied to a directory entry using DS_ModifySync() (or even with DS_AddSync() if it is certain that the change-entry contains only add-modifications).

The change-entry gets the DN from entry1 (if not NULL) or else entry2.

Note that this routine depends on comparing attribute values to detect identical values. DSAPI does not yet support syntax-specific comparisons (e.g. case-ignore comparisons), so values that are equal according to the syntax but appear different will currently count as different values, causing replacements instead of no-change.

Note that any attribute which contains no values at all is treated as if the attribute were not present in the entry.

Parameters
[in]entry1First entry, the base entry for the change, or NULL to use an empty entry as the base.
[in]entry2Second entry, the target entry for the change, or NULL to use an empty entry as the target.
[out]change_pReturned change-entry, which caller must release using DS_Entry_Delete().
Return values
DS_E_BADPARAMentry1 or entry2 is a change-entry, or change_p is NULL
DS_E_NOMEMORYOut of memory
DS_E_NOERROROperation completed without problem.
Since
DSAPI_VERSION 2007
DS_Status DS_Entry_Apply ( const DS_Entry entry1,
const DS_Entry change,
DS_Entry **  entry2_p 
)

Apply a Modify or Add change-entry to a normal entry and return the result as a normal entry.

The resulting entry has its DN copied from entry1 (if not NULL), or else from change.

Note that this routine depends on comparing attribute values to handle delete modifications. DSAPI does not yet support syntax-specific comparisons (e.g. case-ignore comparisons), so deletes will only work at the moment if they match the value exactly.

If one or more delete-modifications fail, then the all the remaining changes are made regardless, and the resulting entry is returned with DS_E_NOTFOUND as the return status.

Parameters
[in]entry1The base entry for the change, or NULL to use an empty entry as the base.
[in]changeChange-entry to apply.
[out]entry2_pEntry that results from applying change to entry1, or NULL. If non-NULL, this must be released using DS_Entry_Delete(). Note that a non-NULL entry is returned if the status is DS_E_NOTFOUND.
Return values
DS_E_BADPARAMentry1 is a change-entry, or change is NULL or not a change-entry, or entry2_p is NULL
DS_E_NOMEMORYOut of memory
DS_E_INTERNALInternal error (bug)
DS_E_NOTFOUNDOne or more delete-modifications could not be applied because matching values were not found; the resulting entry without these changes (which is otherwise completely valid) is returned in *entry_p.
DS_E_NOERROROperation completed without problem.
Since
DSAPI_VERSION 2007