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 | EstimatedTime |
|---|
| 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 |
SEE ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions for the CSSM API:
CSSM_TP_ConfirmCredResult
Functions for the TP SPI:
CSSM_TP_ConfirmCredResult
