DL_DataGetFromUniqueRecordId(3)DL_DataGetFromUniqueRecordId(3)NAME
DL_DataGetFromUniqueRecordId, CSSM_DL_DataGetFromUniqueRecordId - Get
data record (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_DL_DataGetFromUniqueRecordId
(CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_DB_UNIQUE_RECORD_PTR Uni‐
queRecord, 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 Uni‐
queRecord, CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, CSSM_DATA_PTR
Data)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
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. The pointer to a unique record structure returned
from a DL_DataInsert, DL_DataGetFirst, or DL_DataGetNext operation. If
the Attributes structure pointer is NULL, no values are returned.
Otherwise, the DataRecordType, NumberOfAttributes and Attribute‐
Data fields are read. AttributeData must be an array of Num‐
berOfAttributes 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 applica‐
tion 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 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 func‐
tions 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 per‐
forming 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) CSS‐
MERR_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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOM‐
PATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_DB_HANDLE CSS‐
MERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_RECORDTYPE CSS‐
MERR_DL_INVALID_RECORD_UID
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_DL_DataInsert(3), CSSM_DL_DataGetFirst(3), CSSM_DL_DataGetNext(3)
Functions for the DL SPI:
CSSM_DL_DataInsert(3), CSSM_DL_DataGetFirst(3), CSSM_DL_DataGetNext(3)DL_DataGetFromUniqueRecordId(3)