|
|
DL_DataGetFirst(3)
Contents |
DL_DataGetFirst, CSSM_DL_DataGetFirst - Get first data
record (CDSA)
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_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)
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)
Common Security Services Manager library (libcssm.so)
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 contains
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 predicates are
specified, the NumberOfValues of the Attribute of each
selection 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 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 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.
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 provided 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 determined 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 examining 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_DataGetNext() function.
Finally, this function returns a unique record identifier
associated with the retrieved record. This structure can
be used in future references to the retrieved data record.
Once a user has finished 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.
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 are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_DL_ENDOFDATA CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_PARSING_MODULE
CSSMERR_DL_INVALID_QUERY CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT
CSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS
CSSMERR_DL_UNSUPPORTED_OPERATOR CSSMERR_DL_UNSUPPORTED_QUERY
CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS
Books
Intel CDSA Application Developer's Guide (see
CDSA_intro(3))
Reference Pages [Toc] [Back]
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)
[ Back ] |
