TP_ReceiveConfirmation

NAME

CSSM_TP_ReceiveConfirmation — Poll for confirmation (CDSA)

SYNOPSIS

# include <cssm.h>

API:
CSSM_RETURN CSSMAPI CSSM_TP_ReceiveConfirmation
(CSSM_TP_HANDLE TPHandle,
const CSSM_DATA *ReferenceIdentifier,
CSSM_TP_CONFIRM_RESPONSE_PTR *Responses,
sint32 *ElapsedTime)
SPI:
CSSM_RETURN CSSMTPI TP_ReceiveConfirmation
(CSSM_TP_HANDLE TPHandle,
const CSSM_DATA *ReferenceIdentifier,
CSSM_TP_CONFIRM_RESPONSE_PTR *Responses,
sint32 *ElapsedTime)

LIBRARY

Common Security Services Manager library (cdsa$incssm300_shr.exe)

PARAMETERS

`TPHandle` (`input`)		The handle that describes the certification authority module used to perform this function.
`ReferenceIdentifier` (`input`)
		A reference identifier that uniquely identifies a set of service requests and the results created in response to those requests.
`Responses` (`output`)
		An ordered vector of acknowledges indicating the caller's acceptance or rejection of results. The vector contains one acknowledgement per result created by the certificate authority.
`ElapsedTime` (`output`)
		If the confirmation has not been received, this output value is the number of seconds elapsed since the certificate authority created the results or CSSM_ELAPSED_TIME_UNKNOWN. If the confirmation has been received, this output value is CSSM_ELAPSED_TIME_COMPLETE.

DESCRIPTION

A certificate authority uses this function to poll for confirmation from a requester who has been served by the authority. A requester sends a confirmation to the authority by successfully invoking the function CSSM_TP_ConfirmCredResult() (CSSM API), or TP_ConfirmCredResult() (TP SPI).

The ReferenceIdentifier uniquely identifies the service request and corresponding results for which confirmation is expected. This reference identifier need not be identical to the reference identifier used by the requester, but a one-to-one mapping between the two name spaces must be well-defined.

Responses is an ordered vector of acknowledgements indicating, for each returned result, whether the result was accepted or rejected by the original requester for whom the service was performed.

If a result is rejected by the receiver, then the authority process must undo the service if a reverse operation is possible and available.

If a fatal error occurs, this function returns an error code, indicating that the function call can never be completed. If confirmation has not been received, the function return value is CSSM_OK and the ElapsedTime is returned to the caller of this function. The time represents elapsed seconds since the service results were produced by the authority process. Note that there can be a difference between the time the authority process produces the results and the time the results are actually received by the requester. Elapsed time is relative and should increase with consecutive calls using the same ReferenceIdentifier. If the TP module has no knowledge of the elapsed time, the value CSSM_ELAPSED_TIME_UNKNOWN must be returned. If the service requester has confirmed receipt of the service results, this function returns CSSM_OK and ElapsedTime is CSSM_ELAPSED_TIME_COMPLETE.

This function can be invoked repeatedly until the confirmation is received or until the caller decides the acknowledgement may be lost and chooses to undo the results of the original service request.

This function fails if the ReferenceIdentifier is invalid or does not match any requested service for which confirmation is expected.

RETURN VALUE

A CSSM return value combined with elapsed time to indicate one of three results:

`Complete Function`	`Function Return`	`RetrieveOutput`
Result	Value
Confirmation Received	CSSM_OK	CSSM_ELAPSED_TIME_COMPLETE
Confirmation not received, but expected in the future	CSSM_OK	CSSM_ELAPSED_TIME_UNKNOWN or <elapsed seconds>
Fatal Error, Confirmation is not expected	(!CSSM_OK)	NA

For a return value of (!CSSM_OK), the return value is an error code.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_TP_INVALID_IDENTIFIER_POINTER
CSSMERR_TP_INVALID_IDENTIFIER

TP_ReceiveConfirmation

» Table of Contents

» Glossary

» Index