NAME
   TP_ReceiveConfirmation,
   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           CSSM_OK          CSSM_ELAPSED_TIME_COMPLETE
   Received

   Confirmation not       CSSM_OK          CSSM_ELAPSED_TIME_UNKNOWN
   received, but                           or <elapsed seconds>
   expected in the
   future

   Fatal Error,          (!CSSM_OK)        NA
   Confirmation is not
   expected
   _______________________________________________________________________

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

 ERRORS
   Errors are described in the CDSA technical standard.  See CDSA.

        CSSMERR_TP_INVALID_IDENTIFIER_POINTER
        CSSMERR_TP_INVALID_IDENTIFIER

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_TP_ConfirmCredResult

   Functions for the TP SPI:

   CSSM_TP_ConfirmCredResult