CL_CertGetFirstCachedFieldValue

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

CL_CertGetAllTemplateFields

CL_CertGetFirstFieldValue

CL_CertGetFirstCachedFieldValue

Library
Description
Errors

Parameters
Return Value
See Also

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 certificatelibrary module used to perform this function.
`CertHandle` (input)
		A handle identifying a certificate that the applicationhas temporarily cached with the Certificate Library module. Thereferenced certificate is searched for the field value named by `CertField`.
`CertField` (input)
		A pointer to an object identifier that identifiesthe field value to be extracted from the Cert.
`ResultsHandle` (output)
		A pointer to the CSSM_HANDLE that should be usedto 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 thisfunction.
`FieldValue` (output)
		A pointer to the structure containing the valueof 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 setof field values from the cached certificate identified by CertHandle.The selected fields are designated by the CSSM_OID CertField andreturned in the output parameter FieldValue.The OID also identifies the data format of the values returned tothe caller. If multiple OIDs designate the same certificate field,then each such OID defines a distinct data format for the returnedvalues. The function CSSM_CL_CertDescribeFormat() (CSSM API), or CL_CertDescribeFormat() (CL SPI), provides a list of all CSSM_OID values supportedby a certificate library module for naming fields of a certificate.

The CertField OID can identify a singleoccurrence of a set of certificate fields, or multiple occurrencesof a set of certificate fields. If the CertField OIDmatches more than one occurrence, this function outputs the totalnumber of matches and a ResultsHandle to be usedas input to CSSM_CertGetNextCachedFieldValue() (CSM API), or CertGetNextCachedFieldValue() (CL SPI), to retrieve the remaining matches. The firstmatch is returned as the return value of this function.

This function determines the complete set of matches. Thenumber of matches and the selected field values do not change betweenthis 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 particularerror condition. The value CSSM_OK indicates success. All othervalues represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_CL_INVALID_CACHE_HANDLECSSMERR_CL_UNKNOWN_TAGCSSMERR_CL_NO_FIELD_VALUES