NAME

DL_DataGetFirst

SYNOPSIS

CSSM_DB_UNIQUE_RECORD_PTR CSSMDLI DL_DataGetFirst
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_QUERY_PTR Query,
    CSSM_HANDLE_PTR  ResultsHandle,
    CSSM_BOOL  *EndOfDataStore,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR  Data)

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. The DL module can use internally managed indexing structures to enhance the performance of the retrieval operation. This function returns the first record satisfying the query in the list of Attributes and the opaque Data object. This function also returns a flag indicating whether any records satisfied the query and, if so, a results handle to be used when retrieving subsequent records satisfying the query. If the query selection criteria specifies time or space limits for executing the query, those limits also apply to 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.

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 and Data parameter. The CSSM pre-defined attribute names "PrintName" and "Alias" are valid in any query, regardless of the stored value for those attributes. If no query is specified, the DL module can return the first record in the data store (that is, perform sequential retrieval) or return an error.

ResultsHandle (output)

This handle should be used to retrieve subsequent records that satisfied this query.

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 DL handle.

CSSM_DL_INVALID_DB_HANDLE

Invalid DB handle.

CSSM_DL_INVALID_SELECTION_PRED

Invalid selection predicate.

CSSM_DL_NO_DATA_FOUND

No data records match the selection predicate.

CSSM_DL_DATA_GETFIRST_FAIL

An exception occurred when processing the query.

CSSM_DL_MEMORY_ERROR

Error in allocating memory.

SEE ALSO

DL_DataGetNext, DL_DataAbortQuery