DL_DataGetFirst(3)DL_DataGetFirst(3)NAME
DL_DataGetFirst, CSSM_DL_DataGetFirst - Get first data record (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_DL_DataGetFirst (CSSM_DL_DB_HANDLE DLDB‐
Handle, const CSSM_QUERY *Query, CSSM_HANDLE_PTR ResultsHandle,
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, CSSM_DATA_PTR Data,
CSSM_DB_UNIQUE_RECORD_PTR *UniqueId) SPI: CSSM_RETURN CSSMDLI
DL_DataGetFirst (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_QUERY *Query,
CSSM_HANDLE_PTR ResultsHandle, CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR
Attributes, CSSM_DATA_PTR Data, CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)
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 records satisfying the query. The query structure specifying the
selection predicate(s) used to query the data store. The structure con‐
tains meta information about the search fields and the relational and
conjunctive operators forming the selection predicate. The comparison
values to be used in the search are specified in the Attributes field
of this Query structure. If a search attribute is of type
CSSM_DB_ATTRIBUTE_FORMAT_STRING and the search value specified for that
string includes a null-terminator, then the length count for that
string should include the terminating character. (If null-terminators
are used they should be used consistently, storing the terminator as
part of the string in the data store, otherwise selection predicates
will not locate expected matches.) The Query structure attributes also
identify the particular attributes to be searched by this query. If no
query is specified, the DL module can return the first record in the
data store, performing sequential retrieval, or return an error. If no
selection predicates are specified, the DL module can return the first
record in the data store, performing sequential retrieval, or return an
error (CSSM_DL_UNSUPPORTED_NUM_SELECTION_PREDS). When selection predi‐
cates are specified, the NumberOfValues of the Attribute of each selec‐
tion predicate must be 1. If any selection predicate does not satisfy
this requirement, the error CSSMERR_DL_INVALID_QUERY is returned. This
handle should be used to retrieve subsequent records that satisfied
this query. 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
successful and (at least) a record satisfying the query has been
found, then this parameter returns a pointer to a
CSSM_UNIQUE_RECORD_PTR structure containing a unique identifier
associated with the retrieved record. This unique identifier
structure can be used in future references to this record using
this DLDBHandle pairing. It may not be valid for other DLHandles
targeted to this DL module or to other DBHandles targeted to
this data store. If there are no records satisfying the query,
then this pointer is NULL and CSSM_DL_DataGetFirst() must return
CSSM_DL_ENDOFDATA; in this case a normal termination condition
has occurred. The CSSM_DL_FreeUniqueRecord() must be used to de-
allocate this structure.
DESCRIPTION
This function retrieves the first data record in the data store that
matches the selection criteria. The selection criteria (including
selection predicate and comparison values) is specified in the Query
structure. If the Query specifies an attribute that is not defined in
the database's meta-information, an error condition is returned. The DL
module can use internally-managed indexing structures to enhance the
performance of the retrieval operation. This function selects the first
record satisfying the query based on the list of Attributes and the
opaque Data object. The output buffers for the retrieved record are
allocated by this function using the memory management functions pro‐
vided during the module attach operation. This function also returns a
results handle to be used when retrieving subsequent records satisfying
the query.
Additional matching records are iteratively retrieved using the
CSSM_DL_DataGetNext() function . The data storage module supports one
of two retrieval models: Transactional - all query results are deter‐
mined at initial query evaluation. Results do not change during an
incremental retrieval process. File System Scan - query results are
selected during the incremental retrieval process. Records matching the
query may be added to or deleted from the underlying data store during
the iterative retrieval. The caller may receive the new matching
records and not received the deleted records.
The caller can determine which retrieval model is supported by examin‐
ing the encapsulated product description for this data storage module.
If the query selection criteria also specifies time for space limits
for executing the query, those limits also apply ro retrieval of the
additional selected data records retrieved using the CSSM_DL_DataGet‐
Next() function. Finally, this function returns a unique record identi‐
fier associated with the retrieved record. This structure can be used
in future references to the retrieved data record. Once a user has fin‐
ished using a certain query, it must call CSSM_DataAbortQuery() for
releasing resources that CSSM uses. If all records satisfying the query
have been retrieved, then query is automatically terminated.
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_ENDOFDATA CSSMERR_DL_FIELD_SPECIFIED_MULTI‐
PLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_PARSING_MODULE CSS‐
MERR_DL_INVALID_QUERY CSSMERR_DL_INVALID_RECORDTYPE CSS‐
MERR_DL_INVALID_RECORD_UID CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT CSS‐
MERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS CSSMERR_DL_UNSUPPORTED_OPERATOR
CSSMERR_DL_UNSUPPORTED_QUERY CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_DL_DataGetNext(3), CSSM_DL_DataAbortQuery(3)
Functions for the DL SPI:
DL_DataGetNext(3), DL_DataAbortQuery(3)DL_DataGetFirst(3)
