CeReadRecordPropsEx (CEDB) (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function reads properties from the current record.

This function does not work with EDB databases. For more information, see EDB Functions.

A RAPI version of this function exists called CeReadRecordPropsEx (RAPI).

Syntax

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

Parameters

  • hDbase
    [in] Handle to an open database. The database must have been opened by a previous call to the CeOpenDatabaseEx2 (CEDB) function.

  • dwFlags
    [in] Read flag. The following table shows possible values.

    Value Description

    CEDB_ALLOWREALLOC

    Indicates that the LocalAlloc function was used to allocate the buffer specified by the lplpBuffer parameter. The server can reallocate the buffer if it is not large enough to hold the requested properties. The buffer passed in will be freed. You cannot use stack buffers if this flag is set.

    Zero

    Indicates that there are no special instructions for handling the read process.
  • lpcPropID
    [in] Pointer to the number of property identifiers in the array specified by the rgPropID parameter. If rgPropID is set to NULL, this parameter receives the number of properties retrieved.
  • rgPropID
    [in] Pointer to an array of property identifiers for the properties to be retrieved. If this parameter is set to NULL, this function retrieves all properties in the record.
  • lplpBuffer
    [out] Pointer to the address of a pointer to a buffer that receives the requested properties. If the dwFlags parameter includes the CEDB_ALLOWREALLOC flag, the buffer can be reallocated if necessary, even if the function fails. If the CEDB_ALLOWREALLOC flag is specified and the content of this parameter is set to NULL, the server allocates a buffer of the appropriate size in the caller's address space and returns a pointer to the buffer.
  • lpcbBuffer
    [out] Pointer to a variable that contains the size, in bytes, of the buffer specified by the lplpBuffer parameter. When CeReadRecordPropsEx returns, this parameter 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 and CEDB_ALLOWREALLOC was not specified, this parameter can be used to calculate the amount of memory to allocate for the buffer.
  • hHeap
    [in] For Windows CE 2.10 and later, handle to a application-created heap to be used when reallocating memory. This parameter is meaningful only if the CEDB_ALLOWREALLOC flag is set.

Return Value

The object identifier of the record from which the function read indicates success. Zero indicates failure. To get extended error information, call GetLastError. The following table lists possible values.

Value Description

ERROR_INSUFFICIENT_BUFFER

Indicates that the specified 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_INVALID_PARAMETER

Indicates that a parameter was invalid.

ERROR_KEY_DELETED

Indicates that 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_DATA

Indicates that none of the requested properties were found. The output buffer and the size are valid.

ERROR_NO_MORE_ITEMS

Indicates that the current seek pointer is at the end of the database.

Return Value

This function reads the specified set of properties from the current record. If the dwFlags parameter of CeOpenDatabaseEx2 was set to CEDB_AUTOINCREMENT, the function increments the seek pointer so that the next call reads the next record in the current sort order. If there was no active sort order when the database was opened, the order in which records are returned is not predictable.

When rgPropID is set to NULL, this function does not return properties in any specific order. When you set rgPropID to NULL, use a loop to read the properties returned by this function and verify the PropID value of each property, rather than assuming a specific order.

When rgPropID is set to non-NULL, the properties are returned in the order they are listed in rgPropID. If a requested property is not present in the record, the wFlags member of the CEPROPVAL structure is set to CEDB_PROPNOTFOUND.

Read all needed properties from the record in a single call because the entire record is stored in a compressed format. Each time a property is read, it must be decompressed. All the properties are returned in a single marshaled structure, which consists of an array of CEPROPVAL structures. There is one CEPROPVAL structure for each property requested or, if rgPropID is set to NULL, one for each property found.

If a variable-sized property was requested, such as strings or binary large objects (BLOBs) that are packed at the end of the array, the pointers in the CEPROPVAL structures point into this marshaled 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 can have allocated memory on the caller's behalf. You must free the pointer returned by this function if the pointer is not set to NULL.

Requirements

Header windbase.h
Library coredll.lib
Windows Embedded CE Windows CE 2.10 and later

See Also

Reference

CEDB Functions
CeOpenDatabaseEx2 (CEDB)
CeSeekDatabaseEx (CEDB)
CEPROPVAL (CEDB)

Other Resources

LocalAlloc