NAME

   CL_CertGetFirstCachedFieldValue,
   CSSM_CL_CertGetFirstCachedFieldValue - Return values from the cached
                                          certificate (CDSA)

 SYNOPSIS

   # include <cssm.h>

        API:
        CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstCachedFieldValue
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE CertHandle,
        const CSSM_OID *CertField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields,
        CSSM_DATA_PTR *FieldValue)
        SPI:
        CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstCachedFieldValue
        (CSSM_CL_HANDLE CLHandle,
        CSSM_HANDLE CertHandle,
        const CSSM_OID *CertField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields,
        CSSM_DATA_PTR *FieldValue)

 LIBRARY

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

 PARAMETERS

   CLHandle (input)
           The handle that describes the add-in certificate library module
           used to perform this function.

   CertHandle (input)
           A handle identifying a certificate that the application has
           temporarily cached with the Certificate Library module. The
           referenced certificate is searched for the field value named
           by CertField.

   CertField (input)
           A pointer to an object identifier that identifies the field
           value to be extracted from the Cert.

   ResultsHandle (output)
           A pointer to the CSSM_HANDLE that should be used to obtain any
           additional matching fields.

   NumberOfMatchedFields (output)
           The total number of fields that match the CertField OID. This
           count includes the first match, which was returned by this
           function.

   FieldValue (output)
           A pointer to the structure containing the value of the
           requested field. The structure and the field at I
           "(*FieldValue)->Data" are allocated by the service provider.
           The CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue()
           (CL SPI), function can be used to deallocate FieldValue and
           (*FieldValue)->Data.

 DESCRIPTION

   This function returns a single structure containing a set of
   field values from the cached certificate identified by
   CertHandle. The selected fields are designated by the CSSM_OID
   CertField and returned in the output parameter FieldValue. The
   OID also identifies the data format of the values returned to
   the caller. If multiple OIDs designate the same certificate
   field, then each such OID defines a distinct data format for
   the returned values. The function CSSM_CL_CertDescribeFormat()
   (CSSM API), or CL_CertDescribeFormat() (CL SPI), provides a
   list of all CSSM_OID values supported by a certificate library
   module for naming fields of a certificate.

   The CertField OID can identify a single occurrence of a set of
   certificate fields, or multiple occurrences of a set of certificate
   fields. If the CertField OID matches more than one occurrence, this
   function outputs the total number of matches and a ResultsHandle to be
   used as input to CSSM_CertGetNextCachedFieldValue() (CSM API), or
   CertGetNextCachedFieldValue() (CL SPI), to retrieve the remaining
   matches.  The first match is returned as the return value of this
   function.

   This function determines the complete set of matches. The number of
   matches and the selected field values do not change between this
   function and subsequent calls to CSSM_CL_CertGetNextCachedFieldValue()
   (CSSM API), or CL_CertGetNextCachedFieldValue() (CL SPI).

 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.

        CSSMERR_CL_INVALID_CACHE_HANDLE
        CSSMERR_CL_UNKNOWN_TAG
        CSSMERR_CL_NO_FIELD_VALUES

 SEE ALSO

   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_CL_CertGetNextCachedFieldValue
       CSSM_CL_CertAbortCache
       CSSM_CL_CertAbortQuery
       CSSM_CL_CertGetAllFields
       CSSM_CL_CertDescribeFormat
       CSSM_CL_FreeFieldValue

   Functions for the CLI SPI:

       CL_CertGetNextCachedFieldValue
       CL_CertAbortCache
       CL_CertAbortQuery
       CL_CertGetAllFields
       CL_CertDescribeFormat
       CL_FreeFieldValue