NAME

DL_DataGetNext

SYNOPSIS

CSSM_DB_UNIQUE_RECORD_PTR CSSMDLI 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 any additional records satisfying the original query remained to be retrieved. The function also returns a unique record identifier for the returned 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 additional unretrieved records satisfied the query. If TRUE, then additional records satisfying the query can be retrieved using CSSM_DL_DataGetNext. If FALSE, then all records satisfying the query have been retrieved.

Attributes (input/output)

The calling application specifies the names of the attributes to be retrieved. The DL module fills in these attributes' values for the retrieved record. If the Attributes pointer is NULL, the DL module should not return the record's attributes.

Data (output)

The opaque object stored in the retrieved record. If the Data pointer is NULL, the DL module should not return the record's data.

RETURN VALUE

If successful and EndOfDataStore is FALSE, this function returns a pointer to a CSSM_UNIQUE_RECORD 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 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

DL_DataGetFirst, DL_DataAbortQuery