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.

Functions

DS_Status DS_Indication_GetStatus (DS_Indication *indication, DS_ErrorType *type_p)
 Get the directory (operation) error type. More...
 
DS_Status DS_Indication_GetErrorCodes (DS_Indication *indication, DS_ErrorType *type_p, DS_ErrorValue *value_p)
 Get the directory (operation) error type and value codes. More...
 
DS_Status DS_Indication_GetSignatureError (DS_Indication *indication, int *sign_error_p)
 Determine whether signature verification failed for a signed operation. More...
 
DS_Status DS_Indication_GetLimitProblem (DS_Indication *indication, DSLimitProblem *limit_p)
 Get any limit problem associated with a search result. More...
 
DS_Status DS_Indication_GetEntryCount (DS_Indication *indication, int *ret_num_p)
 Return a count of the set of entries contained in the operation outcome. More...
 
DS_Status DS_Indication_GetEntryList (DS_Indication *indication, const DS_EntryList **entry_list_p)
 Return the set of entries contained in the operation outcome. More...
 
DS_EntryDS_Indication_GetFirstEntry (DS_Indication *indication)
 Return the first entry from an Indication. More...
 
DS_Status DS_Indication_GetCompareResult (DS_Indication *indication, int *matched)
 Return a flag indicating whether a compare operation found a match. More...
 
DS_Status DS_Indication_GetTxnStartResult (DS_Indication *indication, unsigned char **txn_id, size_t *txn_id_len)
 Return the result of a transaction start request. On success the result is an identifier in the form of a set of octets (as an 'unsigned char *). More...
 
DS_Status DS_Indication_GetTxnEndResult (DS_Indication *indication, int *fail_msg_id)
 Return the result of a transaction end request. On success error the message ID of the update request that caused the error is set in fail_msg_id. More...
 
DS_Status DS_Indication_GetContinuationReferences (const DS_Indication *indication, const DS_ReferralList **referral_list_p)
 Return the set of continuation references resulting from a search operation. More...
 
DS_Status DS_Indication_GetReferrals (const DS_Indication *indication, const DS_ReferralList **referral_list_p)
 Return information about an operation for which the directory returned a referral. More...
 
DS_Status DS_Indication_GetPasswordPolicyExpiryWarning (const DS_Indication *indication, int *time_before_expiration_p)
 Return the expiry time of the current account's password. More...
 
DS_Status DS_Indication_GetPasswordPolicyGraceWarning (const DS_Indication *indication, int *grace_authentications_remaining_p)
 Return the number of grace authentications left for the current account's password. More...
 
DS_Status DS_Indication_GetPasswordPolicyErrorCode (const DS_Indication *indication, DS_PasswordPolicyError *error_p)
 Return the error code relating to the current account's password. More...
 
DS_Status DS_Indication_GetExtraErrorText (const DS_Indication *indication, const char **error_text_p)
 Determine the supplementary text string returned by the directory. More...
 
DS_Status DS_Indication_HasMoreResults (const DS_Indication *indication, int *more_pages)
 Check if there are more pages for a paged results search. More...
 
void DS_Indication_Delete (DS_Indication *indication)
 Free a DS_Indication structure. More...
 

Detailed Description

Functions used to get operation status and handle results and errors.

The first thing to do with a returned DS_Indication is to check the operation status by calling DS_Indication_GetStatus(). If the status is DS_E_NOERROR then the result handling functions (e.g. DS_Indication_GetEntryList()) can be used to extract result information.

Function Documentation

DS_Status DS_Indication_GetStatus ( DS_Indication indication,
DS_ErrorType type_p 
)

Get the directory (operation) error type.

This can be DS_E_NOERROR or a directory error type (e.g. DS_E_ATTRIBUTE). Note more information is returned using DS_Indication_GetErrorCodes().

Parameters
[in]indicationDirectory operation indication.
[out]type_pReturned operation error type.
Return values
DS_E_BADPARAMEither indication or type_p was NULL
DS_E_NOERRORThe status code was returned
DS_Status DS_Indication_GetErrorCodes ( DS_Indication indication,
DS_ErrorType type_p,
DS_ErrorValue value_p 
)

Get the directory (operation) error type and value codes.

This can be DS_E_NOERROR or a directory error type (e.g. DS_E_ATTRIBUTE), and e.g. DS_E_AT_NOSUCHATTRIBUTE for the value.

Parameters
[in]indicationDirectory operation indication.
[out]type_pReturned operation error type.
[out]value_pReturned operation error value.
Return values
DS_E_BADPARAMEither indication, type_p, or value_p was NULL
DS_E_NOERRORThe status code was returned
Since
DSAPI_VERSION 2001
Examples:
add.c, anonymous.c, async.c, delete.c, modify.c, read.c, and simple.c.
DS_Status DS_Indication_GetSignatureError ( DS_Indication indication,
int *  sign_error_p 
)

Determine whether signature verification failed for a signed operation.

In the case of X.509 signed operations, any result or error will be signed by the server for authentication purposes. In some cases, the signature verification will fail: typically this will happen in the case where an operation was chained to a DSA which was not configured with X.509 strong authentication, but it may also indicate that the signature was invalid. If signature verification fails, then the implication is that the result or error should be treated with caution (for example, the result may be ignored, or displayed to the user along with a message explaining that it may not be authentic).

For unsigned operations, and for signed operations in which signature verification was successful, the value returned by this function will be 0 (zero). A non-zero value indicates that a signed operation failed signature verification.

Parameters
[in]indicationDirectory operation indication.
[out]sign_error_pzero for no signature error; non-zero if signature verification failed.
Return values
DS_E_BADPARAMEither indication or sign_error_p was NULL
DS_E_NOERRORThe status code was returned
Since
DSAPI_VERSION 2012
DS_Status DS_Indication_GetLimitProblem ( DS_Indication indication,
DSLimitProblem limit_p 
)

Get any limit problem associated with a search result.

Parameters
[in]indicationSearch operation indication.
[out]limit_pReturned limit problem.
Return values
DS_E_BADPARMEither indication or limit_p was NULL, or the indication was for a non-search operation.
DS_E_NOERRORThe limit problem was returned.
Since
DSAPI_VERSION 2002
DS_Status DS_Indication_GetEntryCount ( DS_Indication indication,
int *  ret_num_p 
)

Return a count of the set of entries contained in the operation outcome.

Only read and search operations return entries so it only makes sense to use this call for outcomes (DS_Indication) arising from reads and searches.

Parameters
[in]indicationA directory operation outcome (only read or search make sense here).
[out]ret_num_pReturned count.
Return values
DS_E_BADPARAMEither indication or ret_num_p was NULL
DS_E_NOERRORThe number of returned entries was returned
DS_Status DS_Indication_GetEntryList ( DS_Indication indication,
const DS_EntryList **  entry_list_p 
)

Return the set of entries contained in the operation outcome.

Only read and search operations return entries so it only makes sense to use this call for outcomes (DS_Indication) arising from reads and searches.

Parameters
[in]indicationA directory operation outcome (only read or search make sense here).
[out]entry_list_pReturned entry list. NULL if no entries found or there was an error.
Return values
DS_E_BADPARAMEither indication or entry_list_p was NULL
DS_E_NOERRORA list of entries was returned
Examples:
async.c, and read.c.
DS_Entry* DS_Indication_GetFirstEntry ( DS_Indication indication)

Return the first entry from an Indication.

Detach a DS_Entry structure from the list of entries on the DS_Indication, returning it to the caller so that it may be used regardless of what subsequently happens to the DS_Indication.

In many cases, applications will process entries returned by the directory using DS_Indication_GetEntryList to obtain a pointer to a list of entries associated with the DS_Indication. Since such entry information belongs to the DS_Indication, it will no longer be available should the DS_Indication be deleted or updated in a call to DS_NextPageSync.

After using this function, the DS_Entry returned will no longer appear in the DS_Indication's entry list (i.e. it will no longer be part of the list returned by DS_Indication_GetEntryList), and it becomes the caller's responsibility to free the DS_Entry.

To read all of the entries, call this function repeatedly until it returns NULL.

Only read and search operations return entries, so it only makes sense to use this call for outcomes (DS_Indication) arising from reads and searches.

Parameters
[in,out]indicationA directory operation outcome (only read or search make sense here).
Returns
NULL if there are no entries in the Indication
non-NULL a DS_Entry was returned.
Since
DSAPI_VERSION 2033
DS_Status DS_Indication_GetCompareResult ( DS_Indication indication,
int *  matched 
)

Return a flag indicating whether a compare operation found a match.

Only compare operations set this flag, so it only makes sense to use this call for outcomes (DS_Indication) arising from an operation such as DS_CompareSync.

Parameters
[in]indicationA directory operation outcome (only compare makes sense here).
[out]matchednon-zero if the compare matched (i.e. the directory reported that the specified entry contained an attribute with the specified value), zero otherwise.
Return values
DS_E_BADPARAMEither indication or ret_num_p was NULL
DS_E_NOERRORmatched was returned
Since
DSAPI_VERSION 2005
DS_Status DS_Indication_GetTxnStartResult ( DS_Indication indication,
unsigned char **  txn_id,
size_t *  txn_id_len 
)

Return the result of a transaction start request. On success the result is an identifier in the form of a set of octets (as an 'unsigned char *).

Parameters
[in]indicationA directory operation outcome (only transaction start makes sense here).
[out]txn_idIf the request was successful this is filled with the returned transaction ID (must be freed by caller).
[out]txn_id_lenIf the request was successful this is set to the length of the returned transaction ID.
Return values
DS_E_BADPARAMEither indication was NULL or otherwise invalid.
DS_E_NOERRORtransaction ID was returned.
DS_E_DSOPFAILEDthe directory server returned an error.
Since
DSAPI_VERSION 2047
DS_Status DS_Indication_GetTxnEndResult ( DS_Indication indication,
int *  fail_msg_id 
)

Return the result of a transaction end request. On success error the message ID of the update request that caused the error is set in fail_msg_id.

Parameters
[in]indicationA directory operation outcome (only transaction end makes sense here).
[out]fail_msg_idThe ID of the failed update request (when the function returns DS_E_OPFAILED).
Return values
DS_E_BADPARAMEither indication was NULL or otherwise invalid.
DS_E_NOERRORthe transaction end request succeeded..
DS_E_DSOPFAILEDthe directory server returned an error.
Since
DSAPI_VERSION 2047
DS_Status DS_Indication_GetContinuationReferences ( const DS_Indication indication,
const DS_ReferralList **  referral_list_p 
)

Return the set of continuation references resulting from a search operation.

In addition to a list of entries, a successful search operation may also contain one or more continuation references. A continuation reference indicates that additional entries corresponding to the search request may be available from a different directory or directories, and is returned when the local directory is unable or unwilling to propage the request itself.

In addition to using DS_Indication_GetEntryList() to obtain the list of entries, an application should therefore use this function if it wants to process any continuation references (which will involve making separate requests to the directories indicated by any continuation references).

Parameters
[in]indicationA directory operation outcome (only search makes sense here).
[out]referral_list_preturned DS_ReferralList structure, which caller must not free.
Return values
DS_E_BADPARAMentry is NULL or referral_list_p is NULL
DS_E_NOERRORreferral_list_p either points at a DS_ReferralList structure, or has been set to NULL to indicate no continuation references were present.
Since
DSAPI_VERSION 2016
See also
Directory Referrals
DS_Status DS_Indication_GetReferrals ( const DS_Indication indication,
const DS_ReferralList **  referral_list_p 
)

Return information about an operation for which the directory returned a referral.

When an operation is performed that relates to an entry not held on the local directory, the directory will return a DS_E_REFERRAL error if it is not willing, or is unable, to propagate the request itself.

Should an application be interested in following referrals, then this function may be used to determine which other directory server(s) should be contacted.

Parameters
[in]indicationA directory operation outcome which failed with a status of DS_E_REFERRAL.
[out]referral_list_preturned DS_ReferralList structure, which caller must not free.
Return values
DS_E_BADPARAMentry is NULL or referral_list_p is NULL
DS_E_NOERRORreferral_list_p either points at a DS_ReferralList structure, or has been set to NULL to indicate no referral information was present.
Since
DSAPI_VERSION 2016
See also
Directory Referrals
DS_Status DS_Indication_GetPasswordPolicyExpiryWarning ( const DS_Indication indication,
int *  time_before_expiration_p 
)

Return the expiry time of the current account's password.

If the performed operation included a common argument of DS_SVC_PASSWORDPOLICY, the time when the current account's password expires can be retrieved using this function.

Parameters
[in]indicationA directory operation outcome.
[out]time_before_expiration_pReturned time before the password expires.
Return values
DS_E_BADPARAMindication is NULL or time_before_expiration_p is NULL.
DS_E_NOTFOUNDNo expiry time warning was found in the indication, so time_before_expiration_p is unchanged.
DS_E_NOERRORAn expiry time warning was found and returned in time_before_expiration_p.
Since
DSAPI_VERSION 2020
DS_Status DS_Indication_GetPasswordPolicyGraceWarning ( const DS_Indication indication,
int *  grace_authentications_remaining_p 
)

Return the number of grace authentications left for the current account's password.

If the performed operation included a common argument of DS_SVC_PASSWORDPOLICY, the number of remaining grace authentications using the current account's password can be retrieved using this function.

Parameters
[in]indicationA directory operation outcome.
[out]grace_authentications_remaining_pReturned number of grace authentications remaining.
Return values
DS_E_BADPARAMindication is NULL or grace_authentications_remaining_p is NULL.
DS_E_NOTFOUNDNo grace authentications warning was found in the indication, so grace_authentications_remaining_p is unchanged.
DS_E_NOERRORA grace authentications warning was found and returned in grace_authentications_remaining_p.
Since
DSAPI_VERSION 2020
DS_Status DS_Indication_GetPasswordPolicyErrorCode ( const DS_Indication indication,
DS_PasswordPolicyError error_p 
)

Return the error code relating to the current account's password.

If the performed operation included a common argument of DS_SVC_PASSWORDPOLICY, an error code applicable to the current account's password can be retrieved using this function.

Parameters
[in]indicationA directory operation outcome.
[out]error_pReturned error code.
Return values
DS_E_BADPARAMindication is NULL or error_p is NULL.
DS_E_NOTFOUNDNo error code was found in the indication, so error_p is unchanged.
DS_E_NOERRORAn error code was found and returned in error_p.
Since
DSAPI_VERSION 2020
DS_Status DS_Indication_GetExtraErrorText ( const DS_Indication indication,
const char **  error_text_p 
)

Determine the supplementary text string returned by the directory.

Certain directory operations may have supplementary text associated with them (specifically LDAP operations which can return a textual errormessage field). Any such text may be retrieved using this function.

Parameters
[in]indicationA directory operation outcome.
[out]error_text_pPointer to supplementary text (which should not be freed); a value of NULL indicates that no such text was returned by the Directory server.
Return values
DS_E_BADPARAMindication is NULL or error_text_p is NULL.
DS_E_NOERRORerror_text_p now points at the error text (or NULL).
Since
DSAPI_VERSION 2027
DS_Status DS_Indication_HasMoreResults ( const DS_Indication indication,
int *  more_pages 
)

Check if there are more pages for a paged results search.

Search operations requesting paged results return a "cookie" that is uesd to request the next group of results.

Parameters
[in]indicationA search operation outcome.
[out]more_pagesAddress of an integer which will be set to 1 if more pages are available from the server, or 0 if not.
Return values
DS_E_BADPARAMindication is NULL or does not contain a search result, or common_args is NULL, or more_pages is NULL.
DS_E_NOERRORif more_pages was successfully set to 1 or 0.
Since
DSAPI_VERSION 2031
void DS_Indication_Delete ( DS_Indication indication)

Free a DS_Indication structure.

Parameters
[in]indicationThe indication to free, or NULL.
Examples:
add.c, anonymous.c, async.c, delete.c, modify.c, read.c, and simple.c.