Share via

CeReadRecordPropsEx (RAPI)

  • Article

Send Feedback

This function reads properties from the current record of a database on a remote Microsoft® Windows® CE–based device.

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 CeOpenDatabaseEx function.

  • dwFlags
    [in] Specifies read flags. It is one of the following flags.

    Value Description
    0 There are no special instructions for handling the read process.
    CEDB_ALLOWREALLOC 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.

  • lpcPropID
    [in, out] Pointer to the 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
    [in] Pointer to an array of property identifiers for the properties to be retrieved. If this parameter is NULL, CeReadRecordPropsEx 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 may be reallocated if necessary, even if the function fails. If the CEDB_ALLOWREALLOC flag is specified and the pointer pointed to by lplpBuffer is not null it will be released by a call to LocalFree. If the pointer pointed to by lplpBuffer is 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, 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 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 versions 2.10 and later, handle to an application-created heap to be used when reallocating memory. This parameter is only meaningful if the CEDB_ALLOWREALLOC flag is set. As of Windows CE 5.0, this parameter must be set to NULL.

Return Values

The object identifier of the record from which the function read indicates success. Zero indicates failure. To get extended error information, call CeGetLastError and CeRapiGetError. Possible values for CeGetLastError include the following:

  • ERROR_INVALID_PARAMETER
    A parameter was invalid.
  • ERROR_NO_DATA
    None of the requested properties were found. The output buffer and the size are valid.
  • ERROR_INSUFFICIENT_BUFFER
    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_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 CeReadRecordPropsEx function reads the specified set of properties from the current record. If the dwFlags parameter of CeOpenDatabaseEx is 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, then the order in which records are returned is not predictable.

You should read all needed properties from the record in a single call. This is because 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 marshaled structure, which consists of an array of CEPROPVAL structures. There is one CEPROPVAL structure for each property requested or, if rgPropID is NULL, there is one for each property found.

If a property was requested, such as strings or Binary Large Objects (BLOBs) that are packed in 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 may have allocated memory on the caller's behalf. You must free the pointer returned by this function if the pointer is not NULL.

Note   Earlier versions of Windows 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.

Note   The CeReadRecordProps function is obsolete and is replaced by this function.

Requirements

Pocket PC: Pocket PC 2002 and later
Smartphone: Smartphone 2002 and later
OS Versions: Windows CE 3.0 and later
Header: Rapi.h
Library: Rapi.lib

See Also

Remote API Functions | CeOpenDatabaseEx | CEPROPVAL | CeSeekDatabase

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.