Asynchronous Operations on the Directory

Modules
	Handling Directory Operation Results

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