NAME

   CL_CertGetFirstFieldValue,
   CSSM_CL_CertGetFirstFieldValue - Return the value of the certificate
                                    field (CDSA)

 SYNOPSIS

   # include <cssm.h>

        API:
        CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstFieldValue
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert,
        const CSSM_OID *CertField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields,
        CSSM_DATA_PTR *Value)
        SPI:
        CSSM_RETURN CSSMCLI CL_CertGetFirstFieldValue
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Cert,
        const CSSM_OID *CertField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields,
        CSSM_DATA_PTR *Value)

 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.

   Cert (input)
           A pointer to the CSSM_DATA structure containing the certificate.

   CertField (input)
           A pointer to an object identifier which 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.

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

 DESCRIPTION

   This function returns the value of the certificate field designated by
   the CSSM_OID CertField. The OID also identifies the data format for the
   field value returned to the caller. If multiple OIDs name the same
   certificate field, then each such OID defines a distinct data format
   for the returned field value. 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.

   If more than one field matches the CertField OID, the first matching
   field will be returned. The number of matching fields is an output
   parameter, as is the ResultsHandle to be used to retrieve the remaining
   matching fields.

   The set of matching fields is determined by this function. The number of
   matching fields and the field values do not change between this function
   and subsequent calls to CSSM_CL_CertGetNextFieldValue() (CSSM API), or
   CL_CertGetNextFieldValue() (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_CERT_POINTER
        CSSMERR_CL_UNKNOWN_FORMAT
        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_CertGetNextFieldValue
       CSSM_CL_CertAbortQuery
       CSSM_CL_CertGetAllField
       CSSM_CL_FreeFieldValue
       CSSM_CL_CertDescribeFormat
       CSSM_CL_FreeFieldValue

   Functions for the CLI SPI:

       CL_CertGetNextFieldValue
       CL_CertAbortQuery
       CL_CertGetAllField
       CL_FreeFieldValue
       CL_CertDescribeFormat
       CL_FreeFieldValue