Summary: Isode provides a number of APIs which allow integrators and product developers to build components that allow client programs to connect to, query and modify data in the directory.
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_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]sessionPointer to an open directory session
[in]dnDN of entry to read
[in]attr_selectionNULL terminated array of names of attributes to read
[in]common_argsCommon arguments to directory operations
[out]ret_op_idReturned operation ID (on success)
Return values
DS_E_BADDNThe dn was not valid
DS_E_BADPARAMThe attr_selection was invalid
DS_E_DSOPFAILEDThe operation was not sent to the directory
DS_E_NOERRORThe 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_Status DS_TxnStartSync ( DS_Session session,
DS_Indication **  indication_p 
)

Perform a synchronous directory transaction start operation.

Parameters
[in]sessionPointer to an open directory session
[out]indication_pThe result indication
Since
DSAPI_VERSION 2047
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]sessionPointer to an open directory session
[in]IDof transaction to commit.
[in]Whetherto commit (1) or abort/rollback (0).
[out]indication_pThe result indication
Since
DSAPI_VERSION 2047
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]sessionPointer to an open directory session.
[in]op_idRead operation ID.
[out]indication_pReturn result/error.
Return values
DS_E_BADPARAMEither session or indication_p was NULL
DS_E_NOTFOUNDThe op_id was not found
DS_E_NOERRORAn indication was returned
Examples:
async.c.
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]sessionPoiner to an open directory session.
op_id[in] The operation ID being cancelled.
Return values
DS_E_BADPARAMsession was NULL
DS_E_DSOPFAILEDThe operation was not sent to the directory
DS_E_NOERRORThe operation was cancelled