CL_CertGetFirstCachedFieldValueCL_CertGetFirstCachedFieldValue(3)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

       # include <cdsa/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    [Toc]    [Back]

       Common Security Services Manager library (libcssm.so)

PARAMETERS    [Toc]    [Back]

       The handle that describes the add-in  certificate  library
       module  used to perform this function.  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.
   A pointer to an object identifier that identifies
       the field value to be extracted from the Cert.  A  pointer
       to the CSSM_HANDLE that should be used to obtain any additional
 matching fields.  The total number of  fields  that
       match  the  CertField  OID.  This count includes the first
       match, which was returned by this function.  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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       Errors  are described in the CDSA technical standard.  See
       CDSA_intro(3).     CSSMERR_CL_INVALID_CACHE_HANDLE    CSSMERR_CL_UNKNOWN_TAG
 CSSMERR_CL_NO_FIELD_VALUES

SEE ALSO    [Toc]    [Back]

       Books

       Intel    CDSA    Application    Developer's   Guide   (see
       CDSA_intro(3))

       Reference Pages    [Toc]    [Back]

       Functions for the CSSM API:

       CSSM_CL_CertGetNextCachedFieldValue(3), CSSM_CL_CertAbortCache(3),  CSSM_CL_CertAbortQuery(3),  CSSM_CL_CertGetAllFields(3),                  CSSM_CL_CertDescribeFormat(3),
       CSSM_CL_FreeFieldValue(3)

       Functions for the CLI SPI:

       CL_CertGetNextCachedFieldValue(3),   CL_CertAbortCache(3),
       CL_CertAbortQuery(3),  CL_CertGetAllFields(3),  CL_CertDescribeFormat(3), CL_Free