Section Contents

 

 

Handling Directory Operation Results
[Asynchronous Operations on the Directory]


Functions

DS_Status DS_Indication_GetStatus (DS_Indication *indication, DS_ErrorType *type_p)
 Get the directory (operation) error type.
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.
DS_Status DS_Indication_GetSignatureError (DS_Indication *indication, int *sign_error_p)
 Determine whether signature verification failed for a signed operation.
DS_Status DS_Indication_GetLimitProblem (DS_Indication *indication, DSLimitProblem *limit_p)
 Get any limit problem associated with a search result.
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.
DS_Status DS_Indication_GetEntryList (DS_Indication *indication, const DS_EntryList **entry_list_p)
 Return the set of entries contained in the operation outcome.
DS_Status DS_Indication_GetCompareResult (DS_Indication *indication, int *matched)
 Return a flag indicating whether a compare operation found a match.
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.
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.
DS_Status DS_Indication_GetPasswordPolicyExpiryWarning (const DS_Indication *indication, int *time_before_expiration_p)
 Return the expiry time of the current account's password.
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.
DS_Status DS_Indication_GetPasswordPolicyErrorCode (const DS_Indication *indication, DS_PasswordPolicyError *error_p)
 Return the error code relating to the current account's password.
DS_Status DS_Indication_GetExtraErrorText (const DS_Indication *indication, const char **error_text_p)
 Determine the supplementary text string returned by the directory.
void DS_Indication_Delete (DS_Indication *indication)
 Free a DS_Indication structure.

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:
indication [in] Directory operation indication.
type_p [out] Returned operation error type.
Return values:
DS_E_BADPARAM Either indication or status_p was NULL
DS_E_NOERROR The 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:
indication [in] Directory operation indication.
type_p [out] Returned operation error type.
value_p [out] Returned operation error value.
Return values:
DS_E_BADPARAM Either indication or status_p was NULL
DS_E_NOERROR The status code was returned
Since:
DSAPI_VERSION 2001
Examples:
add.c, delete.c, and modify.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:
indication [in] Directory operation indication.
sign_error_p [out] zero for no signature error; non-zero if signature verification failed.
Return values:
DS_E_BADPARAM Either indication or sign_error_p was NULL
DS_E_NOERROR The 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:
indication [in] Search operation indication.
limit_p [out] Returned limit problem.
Return values:
DS_E_BADPARM Either indication or limit_p was NULL, or the indication was for a non-search operation.
DS_E_NOERROR The 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:
indication [in] A directory operation outcome (only read or search make sense here).
ret_num_p [out] Returned count.
Return values:
DS_E_BADPARAM Either indication or ret_num_p was NULL
DS_E_NOERROR The 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:
indication [in] A directory operation outcome (only read or search make sense here).
entry_list_p [out] Returned entry list. NULL if no entries found or there was an error.
Return values:
DS_E_BADPARAM Either indication or entry_list_p was NULL
DS_E_NOERROR A list of entries was returned
Examples:
async.c, and read.c.

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:
indication [in] A directory operation outcome (only compare makes sense here).
matched [out] non-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_BADPARAM Either indication or ret_num_p was NULL
DS_E_NOERROR matched was returned
Since:
DSAPI_VERSION 2005

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:
indication [in] A directory operation outcome (only search makes sense here).
referral_list_p [out] returned DS_ReferralList structure, which caller must not free.
Return values:
DS_E_BADPARAM entry is NULL or referral_list_p is NULL
DS_E_NOERROR referral_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:
indication [in] A directory operation outcome which failed with a status of DS_E_REFERRAL.
referral_list_p [out] returned DS_ReferralList structure, which caller must not free.
Return values:
DS_E_BADPARAM entry is NULL or referral_list_p is NULL
DS_E_NOERROR referral_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:
indication [in] A directory operation outcome.
time_before_expiration_p [out] Returned time before the password expires.
Return values:
DS_E_BADPARAM indication is NULL or time_before_expiration_p is NULL.
DS_E_NOTFOUND No expiry time warning was found in the indication, so time_before_expiration_p is unchanged.
DS_E_NOERROR An 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:
indication [in] A directory operation outcome.
grace_authentications_remaining_p [out] Returned number of grace authentications remaining.
Return values:
DS_E_BADPARAM indication is NULL or grace_authentications_remaining_p is NULL.
DS_E_NOTFOUND No grace authentications warning was found in the indication, so grace_authentications_remaining_p is unchanged.
DS_E_NOERROR A 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:
indication [in] A directory operation outcome.
error_p [out] Returned error code.
Return values:
DS_E_BADPARAM indication is NULL or error_p is NULL.
DS_E_NOTFOUND No error code was found in the indication, so error_p is unchanged.
DS_E_NOERROR An 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:
indication [in] A directory operation outcome.
error_text_p [out] Pointer 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_BADPARAM indication is NULL or error_text_p is NULL.
DS_E_NOERROR error_text_p now points at the error text (or NULL).
Since:
DSAPI_VERSION 2027

void DS_Indication_Delete ( DS_Indication *  indication  ) 

Free a DS_Indication structure.

Parameters:
indication [in] The indication to free, or NULL.
Examples:
add.c, async.c, delete.c, modify.c, and read.c.
Copyright © 2008 Isode privacy   feedback Subscribe to our rss newsfeed