NAME

   CL_CrlGetFirstFieldValue,
   CSSM_CL_CrlGetFirstFieldValue - Get the value of the first CRL
                                   field (CDSA)

 SYNOPSIS

   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_CL_CrlGetFirstFieldValue
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Crl,
        const CSSM_OID *CrlField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields,
        CSSM_DATA_PTR *Value)

    SPI:
        CSSM_RETURN CSSMCLI CL_CrlGetFirstFieldValue
        (CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA *Crl,
        const CSSM_OID *CrlField,
        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.

   Crl (input)
           A pointer to the CSSM_DATA structure that contains the CRL
           from which the field is to be retrieved.

   CrlField (input)
           An object identifier that identifies the field value to be
           extracted from the CRL.

   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 CrlField 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 CRL field designated by the
   CSSM_OID CrlField. The OID also identifies the data format for the
   field value returned to the caller. If multiple OIDs name the same
   CRL field, then each OID defines a distinct data format for the
   returned field value. The function CSSM_CL_CrlDescribeFormat()
   (CSSM API), or CL_CrlDescribeFormat() (CL SPI), provides a list of
   all CSSM_OID values supported by a Certificate Library module for
   naming fields of a CRL.

   If more than one field matches the CrlField 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_CrlGetNextFieldValue()
   (CSSM API), or CL_CrlGetNextFieldValue() (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_CRL_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_CrlGetNextFieldValue
       CSSM_CL_CrlAbortQuery
       CSSM_CL_CrlGetAllFields

   Functions for the CLI SPI:

       CL_CrlGetNextFieldValue
       CL_CrlAbortQuery
       CL_CrlGetAllFields