Synchronous Operations on the Directory

Functions

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. More...
 
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. More...
 
DS_Status DS_NextPageSync (DS_Session *session, DS_Indication *di)
 Request the next page of a paged results search. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

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_ReadSync()

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
[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]indication_pReturn result/error
Return values
DS_E_BADDNIf the dn was invalid
DS_E_BADPARAMEither 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_DSOPFAILEDThe operation was not sent to the directory for a known reason
DS_E_NOERRORThe operation was sent successfully
DS_E_UNKNOWNThe 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_SearchSync()

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
[in]sessionPointer to an open directory session
[in]base_dnDN of search base
[in]filterLDAP search filter
[in]search_scopeScope of search (entry, single level or subtree)
[in]attr_selectionNULL terminated array of attributes to return
[in]common_argsCommon arguments to directory operations.
[out]indication_pReturn result/error.
Return values
DS_E_BADPARAMEither 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_BADFILTERfilter did not contain a valid search filter
DS_E_DSOPFAILEDThe operation failed, more details may be present in the indication_p
DS_E_NAMEA returned result didn't have a valid name
DS_E_NOERRORThe operation was sent successfully. In this case, indication_p will always be non-NULL and will contain information about the result of the operation.
DS_E_UNKNOWNThe operation was not sent to the directory for an unknown reason
DS_E_SIGNEDOPFAILEDA 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_NextPageSync()

DS_Status DS_NextPageSync ( DS_Session session,
DS_Indication di 
)

Request the next page of a paged results search.

The indication passed in must be from an incomplete search using paged results. The indication will be updated with the next page of results, so the caller should extract any necessary results from each indication before calling this function.

Callers wishing to aggregate results from multiple pages may use a series of calls to DS_Indication_GetFirstEntry to obtain DS_Entry structures that will not be lost when the indication is updated with a new page of results.

The DS_Indication_HasMoreResults function can be called to determine if there are more pages to request.

Parameters
[in]sessionPointer to an open directory session
[in,out]diPointer to the previous page's result indication, will be updated.
Since
DSAPI_VERSION 2031

◆ DS_AddSync()

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
[in]sessionPointer to an open directory session
[in]entryThe change-entry being added
[in]common_argsCommon arguments to directory operations.
[out]indication_pThe result indication
Since
DSAPI_VERSION 2000
Examples:
add.c.

◆ DS_AddSyncByDN()

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
[in]sessionPointer to an open directory session
[in]dnDN of entry being added.
[in]attrsAttributes of new entry.
[in]common_argsCommon arguments to directory operations.
[out]indication_pThe result indication
Since
DSAPI_VERSION 2010

◆ DS_DeleteSync()

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
[in]sessionPointer to an open directory session
[in]dnThe name of the entry to be deleted
[in]common_argsCommon arguments to directory operations.
[out]indication_pThe result indication
Since
DSAPI_VERSION 2000
Examples:
delete.c.

◆ DS_ModifySync()

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
[in]sessionPointer to an open directory session
[in]entryThe change-entry containing modifications to apply.
[in]common_argsCommon arguments to directory operations.
[out]indication_pThe result indication
Since
DSAPI_VERSION 2000
Examples:
modify.c.

◆ DS_ModifySyncByDN()

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
[in]sessionPointer to an open directory session
[in]dnDN of entry being modified.
[in]changesAttribute changes.
[in]common_argsCommon arguments to directory operations.
[out]indication_pThe result indication
Since
DSAPI_VERSION 2010

◆ DS_RenameSync()

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
[in]sessionPointer to an open directory session
[in]old_dnThe entry being renamed
[in]new_dnThe new name of the entry
[in]delete_old_rdnSet to 1 if the old RDN values should be deleted
[in]common_argsCommon arguments to directory operations.
[out]indication_pThe result indication
Since
DSAPI_VERSION 2000

◆ DS_CompareSync()

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
[in]sessionPointer to an open directory session
[in]dnThe entry containing the attribute to be compared
[in]attrThe attribute type and value to be compared. Only one value must be present.
[in]common_argsCommon arguments to directory operations.
[out]indication_pThe result indication
Return values
DS_E_NOERRORthe comparison was successfully performed, and indication_p contains the result of the comparison
DS_E_BADPARAMEither session, dn, attr, or indication is NULL
DS_E_BADATTRTYPEIf an unknown attribute is being compared over DAP.
DS_E_BADATTRVALUEattr contained either no values or more than one value.
DS_E_OPFAILEDthe directory was unable to perform the requested operation (the indication may provide more information).
Since
DSAPI_VERSION 2005