CeReadRecordProps

The CeReadRecordProps function reads properties from the current record. A RAPI version of this function exists and is also called CeReadRecordProps.

Syntax

CEOID CeReadRecordProps(HANDLE hDbase, DWORD dwFlags, LPWORD lpcPropID, CEPROPID * rgPropID, LPBYTE * lplpBuffer, LPDWORD lpcbBuffer);

At a Glance

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

Parameters

hDbase

Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabase function.

dwFlags

Read flags. The following value is supported:

CEDB_ALLOWREALLOC: The LocalAlloc function was used to allocate the buffer specified by the lplpBuffer parameter, and the server can reallocate the buffer if it is not large enough to hold the requested properties.

lpcPropID

Number of property identifiers in the array specified by the rgPropID parameter. If rgPropID is NULL, this parameter receives the number of properties retrieved.

rgPropID

Pointer to an array of property identifiers for the properties to be retrieved. If this parameter is NULL, CeReadRecordProps retrieves all properties in the record.

lplpBuffer

Address of a pointer to a buffer that receives the requested properties. If the dwFlags parameter includes the CEDB_ALLOWREALLOC flag, the buffer may be reallocated if necessary. If the CEDB_ALLOWREALLOC flag is specified and this parameter is NULL, the server uses the LocalAlloc function to allocate a buffer of the appropriate size in the caller's address space and returns a pointer to the buffer. Note that if the CEDB_ALLOWREALLOC flag is specified, it is possible for the value of this pointer to change even on failure. For example, the old memory might be freed and the allocation might then fail, leaving the pointer set to NULL.

lpcbBuffer

Pointer to a variable that contains the size, in bytes, of the buffer specified by the lplpBuffer parameter. When CeReadRecordProps returns, lpcbBuffer receives a value that indicates the actual size of the data copied to the buffer. If the buffer was too small to contain the data, this parameter can be used to calculate the amount of memory to allocate for the buffer if CEDB_ALLOWREALLOC was not specified.

Return Values

If the function succeeds, the return value is the object identifier of the record from which the function read. 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 one of the following values:

ERROR_INVALID_PARAMETER: A parameter was invalid.
ERROR_NO_DATA: None of the requested properties was found. The output buffer and the size are valid.
ERROR_INSUFFICIENT_BUFFER: The given buffer was not large enough, and the reallocation failed — if the CEDB_ALLOWREALLOC flag was specified. The lpcbBuffer parameter contains the required buffer size.
ERROR_KEY_DELETED: The record that was about to be read was deleted by another thread. If the current record was reached as a result of an autoseek, this error is not returned, and the next record is returned.
ERROR_NO_MORE_ITEMS: The current seek pointer is at the end of the database.

Remarks

The CeReadRecordProps function reads the specified set of properties from the current record. If the database was opened with the autoseek flag — that is, if the dwFlags parameter of CeOpenDatabase was set to CEDB_AUTOINCREMENT — CeReadRecordProps increments the seek pointer by one so that the next call reads the next record in the current sort order. That is, if the database was opened with a sort order active, then CeReadRecordProps will return the records in sorted order. If the database was not opened with a sort order active, then the order in which records are returned is not predictable.

Read all needed properties from the record in a single call. The entire record is stored in a compressed format, and each time a property is read it must be decompressed. All the properties are returned in a single marshalled structure, which consists of an array of CEPROPVAL structures, one for each property requested — or one for each property found if the application set the rgPropID parameter to NULL when calling the function.

If a property was requested, such as strings or blobs that are packed in at the end of the array, the pointers in the CEPROPVAL structures point into this marshalled structure. This means that the only memory that must be freed is the original pointer to the buffer passed in to the call. Even if the function fails, it may have allocated memory on the caller's behalf. Free the pointer returned by this function if the pointer is not NULL.

For more information, see Accessing Persistent Storage.