CL_CertGetFirstCachedFieldValue

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