NAME
   GetTimeValue,
   CSSM_GetTimeValue,
   CSP_GetTimeValue   - Get a CSP time value (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_GetTimeValue
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_ALGORITHMS TimeAlgorithm,
        CSSM_DATA *TimeData)
    SPI:
        CSSM_RETURN CSSMCSPI CSP_GetTimeValue
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_ALGORITHMS TimeAlgorithm,
        kCSSM_DATA *TimeData)

 LIBRARY
   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETERS
   CSPHandle (input)
           Handle of the cryptographic service provider that will
           perform the operation.

   TimeAlgorithm (input)
           A CSSM algorithm type that indicates the method for fetching
           the time. The following algorithm types are currently
           supported:

           CSSM_ALGID_UTC
                   Returns a time value in the form YYYYMMDDhhmmss
                   (4 characters for the year; 2 characters each for
                   the month, the day, the hour, the minute, and the
                   second). The time returned is GMT.

           CSSM_ALGID_RUNNING_COUNTER
                   The current value of a running hardware counter that
                   operates while the device is in operation. This value
                   can be read from a processor counter provided by some
                   platform architectures.

   TimeData (output)
           The time value of counter value returned in response to the
           request.

 DESCRIPTION
   This function returns a time value maintained by a CSP. This feature
   will be supported primarily by hardware tokens with an onboard real
   time clock.

 NOTES
   The output is returned to the caller either by filling the caller-
   specified buffer or by using the application's declared memory
   allocation functions to allocate buffer space. To specify a specific,
   preallocated output buffer, the caller must provide an array of one
   or more CSSM_DATA structures, each containing a Length field value
   greater than zero and a non-NULL data pointer field value. To specify
   automatic output buffer allocation by the CSP, the caller must
   provide an array of one or more CSSM_DATA structures, each containing
   a Length field value equal to zero and a NULL data pointer field
   value. The application is always responsible for deallocating the
   memory when it is no longer needed.

   Some tokens require authentication before returning a time value.

 RETURN VALUE
   A CSSM_RETURN value indicating success or specifying a particular
   error condition. The value CSSM_OK indicates success. All other
   values represent an error condition.

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

   None specific to this call.

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics