Asynchronous Operations on the Directory

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

Modules
	Handling Directory Operation Results
	Functions used to get operation status and handle results and errors.

Functions
DS_Status	DS_ReadAsync (DS_Session *session, const DS_DN *dn, const char *attr_selection[], DS_CommonArgs *common_args, int *ret_op_id)
	Invoke an asynchronous directory read entry operation. More...
DS_Status	DS_TxnStartSync (DS_Session *session, DS_Indication **indication_p)
	Perform a synchronous directory transaction start operation. More...
DS_Status	DS_TxnEndSync (DS_Session *session, unsigned char *txn_id, size_t txn_id_len, char commit, DS_Indication **indication_p)
	Perform a synchronous directory transaction start (commit) operation. More...
DS_Status	DS_Poll (DS_Session *session, int op_id, DS_Indication **indication_p)
	Poll for an asynchronous operation indication. More...
DS_Status	DS_Cancel (DS_Session *session, int op_id)
	Cancel a previously issued asynchronous operation. More...

Detailed Description

Functions used to perform asynchronous directory operations.

• Read a directory entry.
• Abandon an asynchronous operation.

The basic sequence of operation for asynchronous directory operations is as follows:

1. Invoke asynchronous operation.
2. Poll for result periodically until an indication is returned. The indication can contain a directory result or a directory error.
3. Get the result or error from the returned indication. Read here to see how to process directory indications.

Function Documentation

DS_ReadAsync()

DS_Status DS_ReadAsync	(	DS_Session *	session,
		const DS_DN *	dn,
		const char *	attr_selection[],
		DS_CommonArgs *	common_args,
		int *	ret_op_id
	)

Invoke an asynchronous directory read entry operation.

The caller should subsequently poll for the result using DS_Poll() with the operation ID returned in ret_op_id.

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]	ret_op_id	Returned operation ID (on success)

Return values

DS_E_BADDN	The dn was not valid
DS_E_BADPARAM	The attr_selection was invalid
DS_E_DSOPFAILED	The operation was not sent to the directory
DS_E_NOERROR	The operation was sent successfully

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

async.c.

DS_TxnStartSync()

DS_Status DS_TxnStartSync	(	DS_Session *	session,
		DS_Indication **	indication_p
	)

Perform a synchronous directory transaction start operation.

Parameters

[in]	session	Pointer to an open directory session
[out]	indication_p	The result indication

Since

DSAPI_VERSION 2047

DS_TxnEndSync()

DS_Status DS_TxnEndSync	(	DS_Session *	session,
		unsigned char *	txn_id,
		size_t	txn_id_len,
		char	commit,
		DS_Indication **	indication_p
	)

Perform a synchronous directory transaction start (commit) operation.

Parameters

[in]	session	Pointer to an open directory session
[in]	ID	of transaction to commit.
[in]	Whether	to commit (1) or abort/rollback (0).
[out]	indication_p	The result indication

Since

DSAPI_VERSION 2047

DS_Poll()

DS_Status DS_Poll	(	DS_Session *	session,
		int	op_id,
		DS_Indication **	indication_p
	)

Poll for an asynchronous operation indication.

If the operation (identified by argument op_id) has completed an indication is passed back to the caller in return pointer indication_p. If no result available the return pointer is set to NULL.

Parameters

[in]	session	Pointer to an open directory session.
[in]	op_id	Read operation ID.
[out]	indication_p	Return result/error.

Return values

DS_E_BADPARAM	Either session or indication_p was NULL
DS_E_NOTFOUND	The op_id was not found
DS_E_NOERROR	An indication was returned

Examples

async.c.

DS_Cancel()

DS_Status DS_Cancel	(	DS_Session *	session,
		int	op_id
	)

Cancel a previously issued asynchronous operation.

If the application is no longer interested in getting the result of an earlier asynchronous operation, it may choose to cancel it.

Parameters

[in]	session	Poiner to an open directory session.
	op_id	[in] The operation ID being cancelled.

Return values

DS_E_BADPARAM	session was NULL
DS_E_DSOPFAILED	The operation was not sent to the directory
DS_E_NOERROR	The operation was cancelled