TP_ReceiveConfirmation

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