NAME

CSSM_DL_DataGetNext

SYNOPSIS

CSSM_DB_UNIQUE_RECORD_PTR CSSMAPI CSSM_DL_DataGetNext
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_HANDLE ResultsHandle,
    CSSM_BOOL *EndOfDataStore,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR Data)

DESCRIPTION

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 record values are returned in the Attributes and Data parameters. A flag indicates whether additional records satisfying the original query remain to be retrieved. The function also returns a unique record identifier for the return record.

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 from which records were selected by the initiating query.

ResultsHandle (output)

The handle identifying a set of records retrieved by a query executed by the DataGetFirst function.

EndOfDataStore (output)

A flag indicating whether a record satisfying this query was available to be retrieved in the current operation. If TRUE, then a record was available and was retrieved unless an error condition occurred. If FALSE, then all records satisfying the query have been previously retrieved and no record has been returned by this operation.

Attributes (input/output)

The names of the attributes to be retrieved are input. The DL module fills in these attributes' values from the retrieved record and returns these values as output. If the Attributes pointer is NULL, no values are returned.

Data (output)

The opaque object stored in the retrieved record. If the pointer is NULL, no record is returned.

RETURN VALUE

If successful and EndOfDataStore is FALSE, this function returns a pointer to a CSSM_UNIQUE_RECORD structure containing a 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 the pointer is NULL and EndOfDataStore is TRUE, then a normal termination condition has occurred. If the pointer is NULL and EndOfDataStore is FALSE, then an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_DL_INVALID_DL_HANDLE

Invalid data storage library handle.

CSSM_DL_INVALID_DB_HANDLE

Invalid Data Store handle.

CSSM_DL_INVALID_RESULTS_HANDLE

Invalid query handle.

CSSM_DL_NO_MORE_RECORDS

No more records for this selection handle.

CSSM_DL_DATA_GETNEXT_FAIL

Opening the records caused an exception.

CSSM_DL_MEMORY_ERROR

Error in allocating memory.

SEE ALSO

CSSM_DL_DataGetFirst, CSSM_DL_DataAbortQuery