Directory Entries
[Handling Directory Data]


DS_Status	DS_Entry_GetDN (const DS_Entry entry, const DS_DN *dn_p)
	Get the DN of the given DS_Entry.
DS_Status	DS_Entry_GetNewDN (const DS_Entry entry, const DS_DN *dn_p)
	Get the New DN specified in the given DS_Entry.
DS_Status	DS_Entry_GetDeleteOldRDN (const DS_Entry entry, int flag_p)
	Get the 'delete old RDN' flag for the given DS_Entry.
DS_Status	DS_Entry_SetDN (DS_Entry entry, const DS_DN dn)
	Set the DN of the given DS_Entry.
DS_Status	DS_Entry_SetNewDN (DS_Entry entry, const DS_DN new_dn)
	Set the 'new DN' of the given 'ModDN' DS_Entry.
DS_Status	DS_Entry_SetDeleteOldRDN (DS_Entry *entry, int flag)
	Set the 'Delete Old RDN' flag of the given 'ModDN' DS_Entry.
DS_Status	DS_Entry_IsNormal (const DS_Entry *entry)
	Check that this DS_Entry is a normal entry (i.e. not a change-entry).
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.
DS_Status	DS_Entry_GetType (const DS_Entry entry, DSEntryType type_p)
	Get the type of a DS_Entry.
DS_Status	DS_Entry_Convert (DS_Entry *entry, DSEntryType type)
	Convert a DS_Entry to another type of DS_Entry.
DS_Status	DS_Entry_AddValues (DS_Entry entry, const DS_Attr attr)
	Append an add-attribute (with values) change to a DS_Entry.
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.
DS_Status	DS_Entry_ReplaceValues (DS_Entry entry, const DS_Attr attr)
	Append a replace-attribute-values change to a DS_Entry.
const DS_Entry *	DS_EntryList_GetFirst (const DS_EntryList *entry_list)
	Get the first entry in a list of entries.
const DS_Entry *	DS_EntryList_GetNext (const DS_Entry *entry)
	Get the next entry in a list of entries.
DS_Status	DS_Entry_New (DS_Entry **entryp)
	Create a DS_Entry structure for a Modify change-entry.
DS_Status	DS_Entry_NewType (DS_Entry *entryp, DSEntryType type, const DS_DN dn)
	Create a DS_Entry structure of the given type.
void	DS_Entry_Delete (DS_Entry *entry)
	Free a DS_Entry.
void	DS_EntryList_Delete (DS_EntryList *entry_list)
	Free a DS_Entry list.
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.
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.

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:

	entry	[in] Target entry.
	dn_p	[out] Returned DN, which caller must not free, or NULL for the root DN (default).

Return values:

	DS_E_BADPARAM	Either entry or dn_p was NULL
	DS_E_NOERROR	A 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:

	entry	[in] Target entry.
	dn_p	[out] Returned DN, which caller must not free, or NULL for the root DN.

Return values:

	DS_E_BADPARAM	Either entry or dn_p was NULL, or this isn't a ModDN change-entry.
	DS_E_NOERROR	A 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:

	entry	[in] Target entry.
	flag_p	[out] Returned flag value

Return values:

	DS_E_BADPARAM	Either entry or flag_p was NULL, or this isn't a ModDN change-entry.
	DS_E_NOERROR	The 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:

	entry	[in] Target entry.
	dn	[in] New DN, which will be copied.

Return values:

	DS_E_BADPARAM	Either entry or dn was NULL
	DS_E_NOMEMORY	An internal memory allocation failed
	DS_E_NOERROR	The 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:

	entry	[in] Target ModDN entry.
	new_dn	[in] New DN, which will be copied.

Return values:

	DS_E_BADPARAM	Either entry or new_dn was NULL, or entry is not a ModDN entry
	DS_E_NOMEMORY	An internal memory allocation failed
	DS_E_NOERROR	The 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:

	entry	[in] Target ModDN entry.
	flag	[in] 'Delete Old RDN' flag

Return values:

	DS_E_BADPARAM	Either entry was NULL, or it was not a ModDN entry
	DS_E_NOERROR	The 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:

entry

[in] Target entry.

Return values:

	DS_E_BADPARAM	Either entry is NULL or entry is a change-entry.
	DS_E_NOERROR	The 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:

entry

[in] Target entry.

Return values:

	DS_E_BADPARAM	Either entry is NULL or entry is a normal entry.
	DS_E_NOERROR	The 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:

	entry	[in] Target entry.
	type_p	[out] Type of entry.

Return values:

	DS_E_BADPARAM	entry is NULL
	DS_E_NOERROR	The 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:

	entry	[in] Target entry.
	type	[out] New type of entry.

Return values:

	DS_E_BADPARAM	entry is NULL, or the new type is invalid
	DS_E_BADENTRY	Conversion is being attempted from DSEntryModify, but there are replace- or delete-attribute changes in the entry which cannot be converted
	DS_E_NOERROR	The 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:

	entry	[in] Target change-entry.
	attr	[in] The attribute and values to be added, which will be copied into the entry.

Return values:

	DS_E_BADPARAM	Either entry or attr was NULL, or entry is not of the correct type.
	DS_E_NOMEMORY	An internal memory allocation failed
	DS_E_NOERROR	The 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:

	entry	[in] Target change-entry.
	attr	[in] The attribute and (optional) values to be deleted, which will be copied into the change-entry.

Return values:

	DS_E_BADPARAM	Either entry or attr was NULL, or entry is a normal entry
	DS_E_NOMEMORY	An internal memory allocation failed
	DS_E_NOERROR	The 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:

	entry	[in] Target change-entry.
	attr	[in] The attribute and (optional) values to be replaced, which will be copied into the entry.

Return values:

	DS_E_BADPARAM	Either entry or attr was NULL, or entry is a normal entry
	DS_E_NOMEMORY	An internal memory allocation failed
	DS_E_NOERROR	The 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:

entry_list

[in] Source entry list.

Return values:

	NULL	If there are no entries in the list
	non-NULL	Pointer 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:

entry

[in] Current entry in list.

Return values:

	NULL	If there are no more entries in the list
	non-NULL	Pointer 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:

entryp

[out] Return pointer. The caller should delete this using DS_Entry_Delete().

Return values:

	DS_E_BADPARAM	If entryp was NULL
	DS_E_NOERROR	A DS_Entry was returned
	DS_E_NOMEMORY	A 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:

	entryp	[out] Return pointer. The caller should delete this using DS_Entry_Delete().
	type	[in] Type of DS_Entry to create
	dn	[in] New DN, which will be copied, or NULL if not required

Return values:

	DS_E_BADPARAM	If entryp was NULL or type is invalid
	DS_E_NOERROR	A DS_Entry was returned
	DS_E_NOMEMORY	A memory allocation failed.

Since:: DSAPI_VERSION 2015

void DS_Entry_Delete ( DS_Entry * entry )

Free a DS_Entry.

Parameters:

entry

[in] DS_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:

entry_list

[in] DS_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.

Parameters:

	entry1	[in] First entry, the base entry for the change, or NULL to use an empty entry as the base.
	entry2	[in] Second entry, the target entry for the change, or NULL to use an empty entry as the target.
	change_p	[out] Returned change-entry, which caller must release using DS_Entry_Delete().

Return values:

	DS_E_BADPARAM	entry1 or entry2 is a change-entry, or change_p is NULL
	DS_E_NOMEMORY	Out of memory
	DS_E_NOERROR	Operation 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:

	entry1	[in] The base entry for the change, or NULL to use an empty entry as the base.
	change	[in] Change-entry to apply.
	entry2_p	[out] Entry 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_BADPARAM	entry1 is a change-entry, or change is NULL or not a change-entry, or entry2_p is NULL
	DS_E_NOMEMORY	Out of memory
	DS_E_INTERNAL	Internal error (bug)
	DS_E_NOTFOUND	One 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_NOERROR	Operation completed without problem.

Since:: DSAPI_VERSION 2007

Section Contents

Documentation

Isode Simple Directory API

Directory Entries
[Handling Directory Data]

Function Documentation

Section Contents

Documentation

Isode Simple Directory API

Directory Entries [Handling Directory Data]

Function Documentation

Directory Entries
[Handling Directory Data]