NAME
   CSSM_TP_RetrieveCredResult - Return the results of the credentials
                                request (CDSA)

 SYNOPSIS
   # include <cssm.h>

        CSSM_RETURN CSSMAPI CSSM_TP_RetrieveCredResult
        (CSSM_TP_HANDLE TPHandle,
        const CSSM_DATA *ReferenceIdentifier,
        const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials,
        sint32 *EstimatedTime,
        CSSM_BOOL *ConfirmationRequired,
        CSSM_TP_RESULT_SET_PTR *RetrieveOutput)

 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 the
           CSSM_TP_SubmitCredRequest() call that initiated the
           certificate service request whose results are returned by
           this function. The identifier persists across application
           executions and becomes undefined when all local processing
           of the request has completed.

           Local processing is completed in one of two ways:

             · For certificate services that do not require explicit
               confirmation by the requester, the reference identifier
               is invalidated when the corresponding
               CSSM_TP_RetrieveCredResult() function completes (by
               returning valid results or by failure, which blocks
               returned results).

             · For certificate services that require explicit confirmation
               by the requester, the reference identifier is invalidated
               by successfully invoking the function
               CSSM_TP_ConfirmCredResult().

   CallerAuthCredentials (input/optional)
           This structure contains a set of caller authentication
           credentials.  The authentication information can be a
           passphrase, a PIN, a completed registration form, a
           certificate, or a template of user-specific data. The
           required set of credentials is defined by the service
           provider module and recorded in a record in the MDS Primary
           relation. Multiple credentials can be required.  If the local
           service provider module does not require credentials from a
           caller, then the Credentials field of this verification
           context structure can be NULL. The structure optionally
           contains additional credentials that can be used to support
           the authentication process.  Authentication credentials
           required by the authority should be included in the
           RequestInput. The local TP module can forward information
           from CallerAuthCredentials to the authority, as appropriate,
           but is not required to do so.

   EstimatedTime (output)
           The number of seconds estimated before the results of a
           requested service will be returned to the requester. When the
           local TP module or the authority process cannot estimate the
           time required to perform the requested service, the output
           value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

   ConfirmationRequired (output)
           A Boolean value indicating whether the caller must invoke
           CSSM_TP_ConfirmCredResult() to acknowledge retrieving the
           results of the service request. CSSM_TRUE indicates the
           caller must call CSSM_TP_ConfirmCredResult(). CSSM_FALSE
           indicates that the caller must not call
           CSSM_TP_ConfirmCredResult(). The value of this output
           parameter is not applicable until CSSM_TP_RetrieveCredResult()
           completes by returning results of the request or terminates
           in unrecoverable failure.

   RetrieveOutput (output)
           A pointer to the results returned by the authority in
           response to the service requests submitted by
           CSSM_TP_SubmitCredRequest(). The output results are ordered
           corresponding to the requests.  The structure of the
           response set is determined by the type of request.  The
           caller and the service provider must retain knowledge of
           the request type associated with the ReferenceIdentifier.

 DESCRIPTION
   This function returns the results of a CSSM_TP_SubmitCredRequest()
   call.

   The single identifier ReferenceIdentifier denotes the
   CSSM_TP_SubmitCredRequest() invocation that initiated the request.

   It is possible that the results are not ready to be retrieved when
   this call is made. In that case, an EstimatedTime to complete
   processing is returned. The caller must attempt to retrieve the
   results again after the estimated time to completion has elapsed.

   This function can fail in total for any one of the following reasons:

     ·  The reference identifier is invalid.

     ·  The TP process cannot be located.

     ·  The TP process encountered a fatal error when attempting to
        process the requests.

   When this function completes, the set of return results is ordered
   corresponding to the order of the originating request.

   Some certificate services require the requester to confirm retrieval
   of the results. The ConfirmationRequired parameter indicates whether
   the caller must confirm completion of CSSM_TP_RetrieveCredResult()
   by calling CSSM_TP_ConfirmCredResult().

 RETURN VALUE
   A CSSM_RETURN value combined with estimated time to indicate one of
   three results:

   Complete Function   Function Return   RetrieveOutput   EstimatedTime
        Result              Value
   -----------------   ---------------   --------------   -------------
   Request results        CSSM_OK        Non-NULL pointer     NA
   returned to caller

   Request results not    CSSM_OK        NULL pointer     CSSM_ESTIMATED_
   ready, but expected                                    TIME_UNKNOWN or
   in the future                                      <estimated seconds>

   Fatal Error, results  (!CSSM_OK)         NA            NA
   will never be
   returned

   The (!CSSM_OK) return value represents a specific error code.

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

        CSSMERR_TP_INVALID_IDENTIFIER_POINTER
        CSSMERR_TP_INVALID_IDENTIFIER
        CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER
        CSSMERR_TP_INVALID_POLICY_IDENTIFIERS
        CSSMERR_TP_INVALID_TIMESTRING
        CSSMERR_TP_INVALID_STOP_ON_POLICY
        CSSMERR_TP_INVALID_CALLBACK
        CSSMERR_TP_INVALID_ANCHOR_CERT
        CSSMERR_TP_CERTGROUP_INCOMPLETE
        CSSMERR_TP_INVALID_DL_HANDLE
        CSSMERR_TP_INVALID_DB_HANDLE
        CSSMERR_TP_INVALID_DB_LIST_POINTER
        CSSMERR_TP_INVALID_DB_LIST
        CSSMERR_TP_AUTHENTICATION_FAILED
        CSSMERR_TP_INSUFFICIENT_CREDENTIALS
        CSSMERR_TP_NOT_TRUSTED
        CSSMERR_TP_CERT_REVOKED
        CSSMERR_TP_CERT_SUSPENDED
        CSSMERR_TP_CERT_EXPIRED
        CSSMERR_TP_CERT_NOT_VALID_YET
        CSSMERR_TP_INVALID_CERT_AUTHORITY
        CSSMERR_TP_INVALID_SIGNATURE
        CSSMERR_TP_INVALID_NAME
        CSSMERR_TP_REQUEST_LOST
        CSSMERR_TP_REQUEST_REJECTED

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_TP_SubmitCredRequest

   Functions for the TP SPI:

       TP_SubmitCredRequest