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_Entry *	DS_EntryList_GetFirst (const DS_EntryList *entry_list)
	Get the first entry in a list of entries. More...

const DS_Entry *	DS_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_Entry_GetDN()

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

Get the DN of the given DS_Entry.

Parameters

[in]	entry	Target entry.
[out]	dn_p	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_Entry_GetNewDN()

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]	entry	Target entry.
[out]	dn_p	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_Entry_GetDeleteOldRDN()

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]	entry	Target entry.
[out]	flag_p	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_Entry_SetDN()

DS_Status DS_Entry_SetDN	(	DS_Entry *	entry,
		const DS_DN *	dn
	)

Set the DN of the given DS_Entry.

Parameters

[in]	entry	Target entry.
[in]	dn	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_Entry_SetNewDN()

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]	entry	Target ModDN entry.
[in]	new_dn	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_Entry_SetDeleteOldRDN()

DS_Status DS_Entry_SetDeleteOldRDN	(	DS_Entry *	entry,
		int	flag
	)

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

Parameters

[in]	entry	Target ModDN entry.
[in]	flag	'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_Entry_IsNormal()

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] entry 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_Entry_IsChange()

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] entry 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_Entry_GetType()

DS_Status DS_Entry_GetType	(	const DS_Entry *	entry,
		DSEntryType *	type_p
	)

Get the type of a DS_Entry.

Parameters

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

Return values

DS_E_BADPARAM	entry is NULL
DS_E_NOERROR	The type has been returned.

Since: DSAPI_VERSION 2015

◆ DS_Entry_Convert()

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]	entry	Target entry.
[out]	type	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_Entry_AddValues()

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]	entry	Target change-entry.
[in]	attr	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_Entry_DeleteValues()

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]	entry	Target change-entry.
[in]	attr	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_Entry_ReplaceValues()

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]	entry	Target change-entry.
[in]	attr	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.

◆ DS_EntryList_GetFirst()

const DS_Entry* DS_EntryList_GetFirst ( const DS_EntryList * entry_list )

Get the first entry in a list of entries.

Parameters

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

◆ DS_EntryList_GetNext()

const DS_Entry* DS_EntryList_GetNext ( const DS_Entry * entry )

Get the next entry in a list of entries.

Parameters

[in] entry 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_Entry_New()

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] entryp 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_Entry_NewType()

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]	entryp	Return pointer. The caller should delete this using DS_Entry_Delete().
[in]	type	Type of DS_Entry to create
[in]	dn	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

◆ DS_Entry_Delete()

void DS_Entry_Delete ( DS_Entry * entry )

Free a DS_Entry.

Parameters

[in] entry DS_Entry to free, or NULL.

Examples: add.c, and modify.c.

◆ DS_EntryList_Delete()

void DS_EntryList_Delete ( DS_EntryList * entry_list )

Free a DS_Entry list.

Parameters

[in] entry_list DS_EntryList to free, or NULL.

◆ DS_Entry_Diff()

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]	entry1	First entry, the base entry for the change, or NULL to use an empty entry as the base.
[in]	entry2	Second entry, the target entry for the change, or NULL to use an empty entry as the target.
[out]	change_p	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_Entry_Apply()

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]	entry1	The base entry for the change, or NULL to use an empty entry as the base.
[in]	change	Change-entry to apply.
[out]	entry2_p	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