CeSeekDatabase

The CeSeekDatabase function seeks the specified record in an open database. A RAPI version of this function exists and is also called CeSeekDatabase.

Syntax

CEOID CeSeekDatabase(HANDLE hDatabase, DWORD dwSeekType, DWORD dwValue, LPDWORD lpdwIndex);

At a Glance

Header file:	Winbase.h
Component:	fsdbase
Platforms:	H/PC
Windows CE versions:	1.01 and later

Parameters

hDatabase

Handle to the open database in which to seek.

dwSeekType

Type of seek operation to perform. This parameter can be one of the following values:

CEDB_SEEK_CEOID: Seek until finding an object that has the given object identifier. The dwValue parameter specifies the object identifier. This type of seek operation is very efficient.
CEDB_SEEK_VALUESMALLER: Seek until finding the largest value that is smaller than the given value. If none of the records has a smaller value, the seek pointer is left at the end of the database and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_VALUEFIRSTEQUAL: Seek until finding the first value that is equal to the given value. If the seek operation fails, the seek pointer is left pointing at the end of the database, and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_VALUENEXTEQUAL: Starting from the current seek position, seek exactly one position forward in the sorted order and check if the next record is equal in value to the given value. If so, return the object identifier of this next record; otherwise, return zero and leave the seek pointer at the end of the database. This operation can be used in conjunction with the CEDB_SEEK_VALUEFIRSTEQUAL operation to enumerate all records with an equal value. The dwValue parameter specifies the value for which to seek.
CEDB_SEEK_VALUEGREATER: Seek until finding a value greater than or equal to the given value. If all records are smaller, the seek pointer is left at the end of the database and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure.
CEDB_SEEK_BEGINNING: Seek until finding the record at the given position from the beginning of the database. The dwValue parameter specifies the number of records to seek.
CEDB_SEEK_CURRENT: Seek backward or forward from the current position of the seek pointer for the given number of records. The dwValue parameter specifies the number of records from the current position. The function seeks forward if dwValue is a positive value, or backward if it is negative. A forward seek operation is efficient.
CEDB_SEEK_END: Seek backward for the given number of records from the end of the database. The dwValue parameter specifies the number of records.

dwValue

Value to use for the seek operation. The meaning of this parameter depends on the value of dwSeekType.

lpdwIndex

Pointer to a variable that receives the index from the start of the database to the beginning of the record that was found.

Return Values

If the function succeeds, the return value is the object identifier of the record on which the seek ends. If the function fails, the return value is zero. To get extended error information when within a CE program call GetLastError. If within a RAPI program, call CeGetLastError. GetLastError and CeGetLastError may return ERROR_INVALID_PARAMETER if a parameter is invalid.

Remarks

The CeSeekDatabase function always uses the current sort order as specified in the call to the CeOpenDatabase function. If the CEDB_AUTOINCREMENT flag was specified, an automatic seek of one from the current position is done with each read operation that occurs on the database.

Note that a seek can only be performed on a sorted property value. After creating a database (using CeCreateDatabase) and opening the database (using CeOpenDatabase), subsequent calls to CeSeekDatabase assume the sort order that was specified in the propid parameter of the call to CeOpenDatabase. Although property identifiers can be modified using CeWriteRecordProps, it is best to use the same property identifier for CeOpenDatabase that was used for the propid member of the SORTORDERSPEC structure that was passed in the call to CeCreateDatabase.

To enter negative values for the CEDB_SEEK_CURRENT case, cast a signed long. This changes the effective range on the record indexes to 31 bits from 32.

Multiple sort orders cannot be specified for a single property.

For more information, see Accessing Persistent Storage.