Section Contents

 

 

Asynchronous Operations on the Directory
[Synchronous Operations on the Directory, Invoking Directory Operations]


Modules

 Handling Directory Operation Results
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.
DS_Status DS_Poll (DS_Session *session, int op_id, DS_Indication **indication_p)
 Poll for an asynchronous operation indication.
DS_Status DS_Cancel (DS_Session *session, int op_id)
 Cancel a previously issued asynchronous operation.

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:
session [in] Pointer to an open directory session
dn [in] DN of entry to read
attr_selection [in] NULL terminated array of names of attributes to read
common_args [in] Common arguments to directory operations
ret_op_id [out] 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_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:
session [in] Pointer to an open directory session.
op_id [in] Read operation ID.
indication_p [out] 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_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:
session [in] 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

Copyright © 2008 Isode privacy   feedback Subscribe to our rss newsfeed