|
|
DL_DataGetNext(3)
Contents |
DL_DataGetNext, CSSM_DL_DataGetNext - Get next data record
(CDSA)
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_DL_DataGetNext
(CSSM_DL_DB_HANDLE DLDBHandle, CSSM_HANDLE ResultsHandle,
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
CSSM_DATA_PTR Data, CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)
SPI: CSSM_RETURN CSSMDLI DL_DataGetNext (CSSM_DL_DB_HANDLE
DLDBHandle, CSSM_HANDLE 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 from which records were selected by
the initiating query. The handle identifying a set of
records retrieved by a query executed by the
CSSM_DL_DataGetFirst() function. 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
the pointer is data structure pointer is NULL, the
opaque object is not returned. 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 more records satisfying the query, then this
pointer is NULL and CSSM_DL_DataGetNext() 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 returns the next data record referenced by
the ResultsHandle. The ResultsHandle references a set of
records selected by an invocation of the DataGetFirst
function. 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 metainformation,
an error condition is returned. The record
values are returned in the Attributes and Data parameters.
The output buffers for the retrieved record are allocated
by this function using the memory management functions
provided during the module attach operation. The function
also returns a unique record identifier for the return
record.
The data storage module supports one of two retrieval models:
transactional or file system scan. The transactional
model freezes the set of records to be retrieved at query
initiation. The file system scan model selects from a
potentially changing set of records during the retrieval
process. The EndOfDataStore() function indicates when all
matching records have been retrieved. The caller can
determine which retrieval model is supported by examining
the encapsulated product description for this data storage
module. 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_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID CSSMERR_DL_INVALID_RESULTS_HANDLE
Books
Intel CDSA Application Developer's Guide (see
CDSA_intro(3))
Reference Pages [Toc] [Back]
Functions for the CSSM API:
CSSM_DL_DataGetFirst(3), CSSM_DL_DataAbortQuery(3)
Functions for the DL SPI:
DL_DataGetFirst(3), DL_DataAbortQuery(3)
DL_DataGetNext(3)
[ Back ] | 