 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
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 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)
LIBRARY
Common Security Services Manager library (libcssm.so)
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 records satisfying the query.
Query (input/optional)
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.
ResultsHandle (output)
This handle should be used to retrieve subsequent records that
satisfied this query.
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.
UniqueId (output)
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 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.
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. 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
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|