DL_DataGetNext(3)DL_DataGetNext(3)NAME
DL_DataGetNext, CSSM_DL_DataGetNext - Get next data record (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_DL_DataGetNext (CSSM_DL_DB_HANDLE DLDB‐
Handle, 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)
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 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_DataGet‐
First() function. If the Attributes structure pointer is NULL, no val‐
ues 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
the pointer is data structure pointer is NULL, the opaque object
is not returned. If successful and (at least) a record satisfy‐
ing 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.
DESCRIPTION
This function returns the next data record referenced by the Result‐
sHandle. 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 speci‐
fies an attribute that is not defined in the database's meta-informa‐
tion, 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 man‐
agement 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: transac‐
tional 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.
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_RECORDTYPE CSS‐
MERR_DL_INVALID_RECORD_UID CSSMERR_DL_INVALID_RESULTS_HANDLE
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
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)