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

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_Entry *	DS_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_Indication_GetStatus()

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]	indication	Directory operation indication.
[out]	type_p	Returned operation error type.

Return values

DS_E_BADPARAM	Either indication or type_p was NULL
DS_E_NOERROR	The status code was returned

◆ DS_Indication_GetErrorCodes()

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]	indication	Directory operation indication.
[out]	type_p	Returned operation error type.
[out]	value_p	Returned operation error value.

Return values

DS_E_BADPARAM	Either indication, type_p, or value_p was NULL
DS_E_NOERROR	The 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_Indication_GetSignatureError()

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]	indication	Directory operation indication.
[out]	sign_error_p	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_Indication_GetLimitProblem()

DS_Status DS_Indication_GetLimitProblem	(	DS_Indication *	indication,
		DSLimitProblem *	limit_p
	)

Get any limit problem associated with a search result.

Parameters

[in]	indication	Search operation indication.
[out]	limit_p	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_Indication_GetEntryCount()

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]	indication	A directory operation outcome (only read or search make sense here).
[out]	ret_num_p	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_Indication_GetEntryList()

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]	indication	A directory operation outcome (only read or search make sense here).
[out]	entry_list_p	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_Indication_GetFirstEntry()

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] indication A 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_Indication_GetCompareResult()

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]	indication	A directory operation outcome (only compare makes sense here).
[out]	matched	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_Indication_GetTxnStartResult()

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]	indication	A directory operation outcome (only transaction start makes sense here).
[out]	txn_id	If the request was successful this is filled with the returned transaction ID (must be freed by caller).
[out]	txn_id_len	If the request was successful this is set to the length of the returned transaction ID.

Return values

DS_E_BADPARAM	Either indication was NULL or otherwise invalid.
DS_E_NOERROR	transaction ID was returned.
DS_E_DSOPFAILED	the directory server returned an error.

Since: DSAPI_VERSION 2047

◆ DS_Indication_GetTxnEndResult()

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]	indication	A directory operation outcome (only transaction end makes sense here).
[out]	fail_msg_id	The ID of the failed update request (when the function returns DS_E_OPFAILED).

Return values

DS_E_BADPARAM	Either indication was NULL or otherwise invalid.
DS_E_NOERROR	the transaction end request succeeded..
DS_E_DSOPFAILED	the directory server returned an error.

Since: DSAPI_VERSION 2047

◆ DS_Indication_GetContinuationReferences()

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]	indication	A directory operation outcome (only search makes sense here).
[out]	referral_list_p	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_Indication_GetReferrals()

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]	indication	A directory operation outcome which failed with a status of DS_E_REFERRAL.
[out]	referral_list_p	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_Indication_GetPasswordPolicyExpiryWarning()

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]	indication	A directory operation outcome.
[out]	time_before_expiration_p	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_Indication_GetPasswordPolicyGraceWarning()

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]	indication	A directory operation outcome.
[out]	grace_authentications_remaining_p	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_Indication_GetPasswordPolicyErrorCode()

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]	indication	A directory operation outcome.
[out]	error_p	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_Indication_GetExtraErrorText()

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]	indication	A directory operation outcome.
[out]	error_text_p	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

◆ DS_Indication_HasMoreResults()

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]	indication	A search operation outcome.
[out]	more_pages	Address 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_BADPARAM	indication is NULL or does not contain a search result, or common_args is NULL, or more_pages is NULL.
DS_E_NOERROR	if more_pages was successfully set to 1 or 0.

Since: DSAPI_VERSION 2031

◆ DS_Indication_Delete()

void DS_Indication_Delete ( DS_Indication * indication )

Free a DS_Indication structure.

Parameters

[in] indication The indication to free, or NULL.

Examples: add.c, anonymous.c, async.c, delete.c, modify.c, read.c, and simple.c.