Section Contents

 

 

Synchronous Operations on the Directory
[Invoking Directory Operations]


Modules

 Asynchronous Operations on the Directory
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.
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.
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.
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.
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.
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.
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.
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.
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.

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_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:
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
indication_p [out] 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_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:
session [in] Pointer to an open directory session
base_dn [in] DN of search base
filter [in] LDAP search filter
search_scope [in] Scope of search (entry, single level or subtree)
attr_selection [in] NULL terminated array of attributes to return
common_args [in] Common arguments to directory operations.
indication_p [out] 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 was not sent to the directory for a known reason
DS_E_NAME A returned result didn't have a valid name
DS_E_NOERROR The operation was sent successfully
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_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:
session [in] Pointer to an open directory session
entry [in] The change-entry being added
common_args [in] Common arguments to directory operations.
indication_p [out] The result indication
Since:
DSAPI_VERSION 2000
Examples:
add.c.

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:
session [in] Pointer to an open directory session
dn [in] DN of entry being added.
attrs [in] Attributes of new entry.
common_args [in] Common arguments to directory operations.
indication_p [out] The result indication
Since:
DSAPI_VERSION 2010

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:
session [in] Pointer to an open directory session
dn [in] The name of the entry to be deleted
common_args [in] Common arguments to directory operations.
indication_p [out] The result indication
Since:
DSAPI_VERSION 2000
Examples:
delete.c.

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:
session [in] Pointer to an open directory session
entry [in] The change-entry containing modifications to apply.
common_args [in] Common arguments to directory operations.
indication_p [out] The result indication
Since:
DSAPI_VERSION 2000
Examples:
modify.c.

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:
session [in] Pointer to an open directory session
dn [in] DN of entry being modified.
changes [in] Attribute changes.
common_args [in] Common arguments to directory operations.
indication_p [out] The result indication
Since:
DSAPI_VERSION 2010

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:
session [in] Pointer to an open directory session
old_dn [in] The entry being renamed
new_dn [in] The new name of the entry
delete_old_rdn [in] Set to 1 if the old RDN values should be deleted
common_args [in] Common arguments to directory operations.
indication_p [out] The result indication
Since:
DSAPI_VERSION 2000

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:
session [in] Pointer to an open directory session
dn [in] The entry containing the attribute to be compared
attr [in] The attribute type and value to be compared. Only one value must be present.
common_args [in] Common arguments to directory operations.
indication_p [out] 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

Copyright © 2008 Isode privacy   feedback Subscribe to our rss newsfeed