NAME
CSSM_DL_DataGetFromUniqueRecordId — Get data record (CDSA)
SYNOPSIS
# include <cssm.h>
API:
CSSM_RETURN CSSMAPI CSSM_DL_DataGetFromUniqueRecordId
(CSSM_DL_DB_HANDLE DLDBHandle,
const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord,
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
CSSM_DATA_PTR Data)
SPI:
CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordId
(CSSM_DL_DB_HANDLE DLDBHandle,
const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord,
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
CSSM_DATA_PTR Data) |
LIBRARY
Common Security Services Manager library (cdsa$incssm300_shr.exe)
PARAMETERS
| DLDBHandle (input) |
| | | The handle pair that describes the add-in data storage
library module to be used to perform this function and the open
data store to search for the data record. |
| UniqueRecord (input) |
| | | The pointer to a unique record structure returned
from a DL_DataInsert, DL_DataGetFirst,
or DL_DataGetNext operation. |
| Attributes (optional-input/output) |
| | | If the Attributes structure pointer
is NULL, no values are returned. Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields
are read. AttributeData must be an array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE
elements. Only the Info field of each element
is used on input. The AttributeFormat field of
the Info field is ignored on input. On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing
a list of all or the requested attribute values (subset) from the
retrieved record. The SemanticInformation field
is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData array,
the NumberOfValues field is set to reflect the
size of the Value array which is allocated by
the DL using the application specified allocators. Each CSSM_DATA
in the Value array will have it's Data field
as a pointer to data allocated using the application specified allocators
containing the attributes value, and have it's Length set
to the length of the value. All values for an attribute are returned (this could be 0).
All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA
are left unchanged except for the AttributeFormat field, which
is set to reflect the schema. |
| Data (optional-input/output) |
| | | Data values contained in the referenced memory are
ignored during processing and are overwritten with the retrieved
opaque object. On output, a CSSM_DATA structure containing the opaque
object stored in the retrieved record. If the pointer is data structure pointer
is NULL, the opaque object is not returned. |
DESCRIPTION
This function retrieves the data record and attributes associated
with this unique record identifier. The Attributes parameter
can specify a subset of the attributes to be returned. If Attributes specifies
an attribute that is not defined in the database's meta-information,
an error condition is returned. The output buffers for the retrieved
record are allocated by this function using the memory management
functions provided during the module attach operation. The DL module
can use an indexing structure identified in the UniqueRecordId to
enhance the performance of the retrieval operation.
The DL should assume that the value of CSSM_QUERY_FLAGS is
when performing this operation. In particular this means that if
the data of a key record is being retrieved, the DL will return
a CSSM_KEY structure with a key reference.
If the record referenced by UniqueRecordIdentifier has
been modified since the last time it was retrieved, the error (warning)
CSSMERR_DL_RECORD_MODIFIED is returned but the requested attributes
and data of the new record is returned. The caller should be advised
that other attributes (or the data) might have changed that were
not fetched from the DL with this call.
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.
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID |
SEE ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions for the CSSM API:
CSSM_DL_DataInsert, CSSM_DL_DataGetFirst, CSSM_DL_DataGetNext
Functions for the DL SPI:
CSSM_DL_DataInsert, CSSM_DL_DataGetFirst, CSSM_DL_DataGetNext
