NAME
CSSM_DL_DataGetFirst — Get first data record (CDSA)
SYNOPSIS
# include <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 (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 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 deallocate 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.
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
Online Help
Functions for the CSSM API:
CSSM_DL_DataGetNext, CSSM_DL_DataAbortQuery
Functions for the DL SPI:
DL_DataGetNext, DL_DataAbortQuery
