Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function seeks the specified record in an open database on a remote Windows Embedded CE–based device.

Syntax 

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

Parameters

hDatabase

[in] Handle to the open database in which to seek the record.

dwSeekType

[in] Specifies the type of seek operation to perform. It is one of the values in the following table.

Value Description

CEDB_SEEK_CEOID

Seek until finding an object that has the specified object identifier. The dwValueparameter specifies the object identifier. This type of seek operation is very efficient.

CEDB_SEEK_VALUESMALLER

Starting from the current position, seeks backward toward the start of the sort. Always seeks backward, regardless of sort order. In ascending order, this finds the largest value smaller than the specified value; in descending order, this finds the smallest value larger than the specified value.

If none of the previous records has a value that meets the search criteria, the seek pointer is left at the end of the database and the function returns 0. The dwValueparameter is a pointer to a CEPROPVALstructure.

CEDB_SEEK_VALUEFIRSTEQUAL

Begins at the start of the sort and seeks forward until finding the first value that is equal to the specified value. Always seeks forward, regardless of sort order. If the seek operation fails, the seek pointer is left at the end of the database, and the function returns 0. The dwValueparameter is a pointer to a CEPROPVALstructure.

CEDB_SEEK_VALUENEXTEQUAL

Starting from the current seek position, seeks exactly one position forward in the sorted order and checks if the next record is equal in value to the specified value. If so, returns the object identifier of this next record; otherwise, returns 0 and leaves 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 dwValueparameter is a pointer to a CEPROPVALstructure.

CEDB_SEEK_VALUEGREATER

Starting from the current position, seeks backward toward the start of the sort. Always seeks forward, regardless of sort order. In ascending order this finds the smallest value greater than the specified value; in descending order this finds the largest value smaller than the specified value.

If none of the following records has a value that meets the search criteria, the seek pointer is left at the end of the database and the function returns 0. The dwValueparameter is a pointer to a CEPROPVALstructure.

CEDB_SEEK_BEGINNING

Seeks until finding the record at the specified position from the beginning of the database. The dwValueparameter specifies the number of records to seek from the beginning.

CEDB_SEEK_CURRENT

Seeks backward or forward from the current position of the seek pointer for the specified number of records. The dwValueparameter specifies the number of records to seek from the current position. The function seeks forward if dwValueis a positive value, or backward if it is negative.

CEDB_SEEK_END

Seeks backward for the specified number of records from the end of the database. The dwValueparameter specifies the number of records to seek from the end.
dwValue

[in] Specifies the value to use for the seek operation. The meaning of this parameter depends on the value of dwSeekType.

lpdwIndex

[out] Pointer to a variable that receives the index from the start of the database to the beginning of the record that was found. This parameter can be NULL.

Note:
Passing a non-NULL value for lpdwIndexwill cause the call to be slower, and should be avoided whenever possible.

Return Value

The object identifier of the record on which the seek ends indicates success. Zero indicates failure. To get extended error information, call CeGetLastErrorand CeRapiGetError. CeGetLastErrormay return ERROR_INVALID_PARAMETER if a parameter is invalid.

Remarks

The CeSeekDatabasemethod always uses the current sort order of the database.

If the database was opened using CeOpenDatabaseand the CEDB_AUTOINCREMENT flag was specified for the dwFlagsparameter , the database pointer is incremented by one record 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 CeCreateDatabaseExand opening the database using CeOpenDatabaseEx, subsequent calls to CeSeekDatabaseassume the sort order that was specified in the propidparameter of the call to CeOpenDatabaseEx.

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

Multiple sort orders cannot be specified for a single property.

When a CEPROPVALstructure is required to seek, the propidparameter must be set to PROPID of the sort order specified in the CeOpenDatabaseExcall.

Note:
Earlier versions of Windows Embedded CE assigned object identifiers to objects in other file systems, such as the file allocation table (FAT) file system. These object identifiers were guaranteed to be unique within a volume, but not across multiple volumes. Effective with version 3.0, only objects in the object store have valid, unique object identifiers and the object store is the only volume that can return an object identifier.

Requirements

Header rapi.h
Library rapi.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2002 and later, Smartphone 2002 and later

See Also