Functions used to perform synchronous directory operations. More...

Functions
DS_Status	DS_ReadSync (DS_Session session, const DS_DN dn, const char attr_selection[], DS_CommonArgs common_args, DS_Indication **indication_p)
	Perform a synchronous directory read entry operation. More...

DS_Status	DS_SearchSync (DS_Session session, const DS_DN base_dn, const char filter, DSSearchScope search_scope, const char attr_selection[], DS_CommonArgs common_args, DS_Indication *indication_p)
	Perform a synchronous directory search operation. More...

DS_Status	DS_NextPageSync (DS_Session session, DS_Indication di)
	Request the next page of a paged results search. More...

DS_Status	DS_AddSync (DS_Session session, const DS_Entry entry, const DS_CommonArgs common_args, DS_Indication *indication_p)
	Perform a synchronous directory add operation. More...

DS_Status	DS_AddSyncByDN (DS_Session session, const DS_DN dn, const DS_AttrList attrs, const DS_CommonArgs common_args, DS_Indication **indication_p)
	Perform a synchronous directory add operation. More...

DS_Status	DS_DeleteSync (DS_Session session, const DS_DN dn, const DS_CommonArgs common_args, DS_Indication *indication_p)
	Perform a synchronous directory delete operation. More...

DS_Status	DS_ModifySync (DS_Session session, const DS_Entry entry, const DS_CommonArgs common_args, DS_Indication *indication_p)
	Perform a synchronous directory modify operation. More...

DS_Status	DS_ModifySyncByDN (DS_Session session, const DS_DN dn, const DS_AttrList changes, const DS_CommonArgs common_args, DS_Indication **indication_p)
	Perform a synchronous directory modify operation. More...

DS_Status	DS_RenameSync (DS_Session session, const DS_DN old_dn, const DS_DN new_dn, int delete_old_rdn, const DS_CommonArgs common_args, DS_Indication **indication_p)
	Perform a synchronous directory rename operation. More...

DS_Status	DS_CompareSync (DS_Session session, const DS_DN dn, const DS_Attr attr, const DS_CommonArgs common_args, DS_Indication **indication_p)
	Perform a synchronous directory compare operation. More...

Detailed Description

Functions used to perform synchronous directory operations.

Read a directory entry.
Search for directory entries.
Add a new directory entry.
Delete a directory entry.
Modify an existing directory entry.
Rename an existing directory entry.

All directory operations (other than binds) return a directory indication. Read here to see how to process directory indications.

Function Documentation

◆ DS_ReadSync()

DS_Status DS_ReadSync	(	DS_Session *	session,
		const DS_DN *	dn,
		const char *	attr_selection[],
		DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory read entry operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	dn	DN of entry to read
[in]	attr_selection	NULL terminated array of names of attributes to read
[in]	common_args	Common arguments to directory operations
[out]	indication_p	Return result/error

Return values

DS_E_BADDN	If the dn was invalid
DS_E_BADPARAM	Either session or dn or indication_p was NULL, or attr_selection was invalid, or common_args specified DS_SEC_SIGNED and this session is not strongly bound.
DS_E_DSOPFAILED	The operation was not sent to the directory for a known reason
DS_E_NOERROR	The operation was sent successfully
DS_E_UNKNOWN	The operation was not sent to the directory for an unknown reason

The attr_selection array lists the attributes that should be returned. A NULL array, or an array with a single NULL value, is interpreted as a request for all user attributes. Otherwise, the array can contain combinations of these items:

an LDAPv3 attribute type name (e.g. "cn")
the string "*" to request all user attributes
the string "+" to request all operational attributes

An array consisting of the string "1.1" and a NULL is interpreted as a request for no attributes.

It is not permitted to request all user attributes and all operational attributes and a list of specific attributes.

Examples: read.c.

◆ DS_SearchSync()

DS_Status DS_SearchSync	(	DS_Session *	session,
		const DS_DN *	base_dn,
		const char *	filter,
		DSSearchScope	search_scope,
		const char *	attr_selection[],
		DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory search operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	base_dn	DN of search base
[in]	filter	LDAP search filter
[in]	search_scope	Scope of search (entry, single level or subtree)
[in]	attr_selection	NULL terminated array of attributes to return
[in]	common_args	Common arguments to directory operations.
[out]	indication_p	Return result/error.

Return values

DS_E_BADPARAM	Either session or filter or indication_p was NULL, or base_dn was in invalid DN, or search_scope was invalid, or attr_selection was invalid, or common_args specified DS_SEC_SIGNED and this session is not strongly bound.
DS_E_BADFILTER	filter did not contain a valid search filter
DS_E_DSOPFAILED	The operation failed, more details may be present in the indication_p
DS_E_NAME	A returned result didn't have a valid name
DS_E_NOERROR	The operation was sent successfully. In this case, indication_p will always be non-NULL and will contain information about the result of the operation.
DS_E_UNKNOWN	The operation was not sent to the directory for an unknown reason
DS_E_SIGNEDOPFAILED	A signed search operation completed, but its signature failed to verify. No search results are returned.

The attr_selection array lists the attributes that should be returned. A NULL array, or an array with a single NULL value, is interpreted as a request for all user attributes. Otherwise, the array can contain combinations of these items:

an LDAPv3 attribute type name (e.g. "cn")
the string "*" to request all user attributes
the string "+" to request all operational attributes

An array consisting of the string "1.1" and a NULL is interpreted as a request for no attributes.

It is not permitted to request all user attributes and all operational attributes and a list of specific attributes.

◆ DS_NextPageSync()

DS_Status DS_NextPageSync	(	DS_Session *	session,
		DS_Indication *	di
	)

Request the next page of a paged results search.

The indication passed in must be from an incomplete search using paged results. The indication will be updated with the next page of results, so the caller should extract any necessary results from each indication before calling this function.

Callers wishing to aggregate results from multiple pages may use a series of calls to DS_Indication_GetFirstEntry to obtain DS_Entry structures that will not be lost when the indication is updated with a new page of results.

The DS_Indication_HasMoreResults function can be called to determine if there are more pages to request.

Parameters

[in]	session	Pointer to an open directory session
[in,out]	di	Pointer to the previous page's result indication, will be updated.

Since: DSAPI_VERSION 2031

◆ DS_AddSync()

DS_Status DS_AddSync	(	DS_Session *	session,
		const DS_Entry *	entry,
		const DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory add operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	entry	The change-entry being added
[in]	common_args	Common arguments to directory operations.
[out]	indication_p	The result indication

Since: DSAPI_VERSION 2000

Examples: add.c.

◆ DS_AddSyncByDN()

DS_Status DS_AddSyncByDN	(	DS_Session *	session,
		const DS_DN *	dn,
		const DS_AttrList *	attrs,
		const DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory add operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	dn	DN of entry being added.
[in]	attrs	Attributes of new entry.
[in]	common_args	Common arguments to directory operations.
[out]	indication_p	The result indication

Since: DSAPI_VERSION 2010

◆ DS_DeleteSync()

DS_Status DS_DeleteSync	(	DS_Session *	session,
		const DS_DN *	dn,
		const DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory delete operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	dn	The name of the entry to be deleted
[in]	common_args	Common arguments to directory operations.
[out]	indication_p	The result indication

Since: DSAPI_VERSION 2000

Examples: delete.c.

◆ DS_ModifySync()

DS_Status DS_ModifySync	(	DS_Session *	session,
		const DS_Entry *	entry,
		const DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory modify operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	entry	The change-entry containing modifications to apply.
[in]	common_args	Common arguments to directory operations.
[out]	indication_p	The result indication

Since: DSAPI_VERSION 2000

Examples: modify.c.

◆ DS_ModifySyncByDN()

DS_Status DS_ModifySyncByDN	(	DS_Session *	session,
		const DS_DN *	dn,
		const DS_AttrList *	changes,
		const DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory modify operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	dn	DN of entry being modified.
[in]	changes	Attribute changes.
[in]	common_args	Common arguments to directory operations.
[out]	indication_p	The result indication

Since: DSAPI_VERSION 2010

◆ DS_RenameSync()

DS_Status DS_RenameSync	(	DS_Session *	session,
		const DS_DN *	old_dn,
		const DS_DN *	new_dn,
		int	delete_old_rdn,
		const DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory rename operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	old_dn	The entry being renamed
[in]	new_dn	The new name of the entry
[in]	delete_old_rdn	Set to 1 if the old RDN values should be deleted
[in]	common_args	Common arguments to directory operations.
[out]	indication_p	The result indication

Since: DSAPI_VERSION 2000

◆ DS_CompareSync()

DS_Status DS_CompareSync	(	DS_Session *	session,
		const DS_DN *	dn,
		const DS_Attr *	attr,
		const DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

Perform a synchronous directory compare operation.

This function may be used to test whether a directory entry contains an attribute containing a specific attribute value. For a successful operation, a DS_Indication is returned, with the error_type field set to DS_E_SUCCESS, and a flag indicating whether the directory found a match for the specified attribute/value pair. The function DS_Indication_GetCompareResult() should be used to read this flag.

Parameters

[in]	session	Pointer to an open directory session
[in]	dn	The entry containing the attribute to be compared
[in]	attr	The attribute type and value to be compared. Only one value must be present.
[in]	common_args	Common arguments to directory operations.
[out]	indication_p	The result indication

Return values

DS_E_NOERROR	the comparison was successfully performed, and indication_p contains the result of the comparison
DS_E_BADPARAM	Either session, dn, attr, or indication is NULL
DS_E_BADATTRTYPE	If an unknown attribute is being compared over DAP.
DS_E_BADATTRVALUE	attr contained either no values or more than one value.
DS_E_OPFAILED	the directory was unable to perform the requested operation (the indication may provide more information).

Since: DSAPI_VERSION 2005