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 method reads properties from the current record of a database on a remote Windows Embedded CE–based device.

Note:
This method has been deprecated. Use IRAPISession::CeReadRecordPropsExinstead.

Syntax 

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

Parameters

hDbase

[in] Handle to an open database. The database must have been opened by a previous call to the IRAPISession::CeOpenDatabasemethod.

dwFlags

[in] Specifies a bitmask of 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 LocalAllocfunction was used to allocate the buffer specified by the lplpBufferparameter. 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 rgPropIDparameter. If rgPropIDis 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, IRAPISession:CeReadRecordPropsretrieves all properties in the record.

lplpBuffer

[out] Pointer to a long pointer to a buffer that receives the requested properties. If the dwFlagsparameter 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 LocalAllocfunction 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

[out] Long pointer to a variable that contains the size, in bytes, of the buffer specified by the lplpBufferparameter. When IRAPISession::CeReadRecordPropsreturns, lpcbBufferreceives 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 Value

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

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 specified buffer was not large enough, and the reallocation failed — if the CEDB_ALLOWREALLOC flag was specified. The lpcbBufferparameter 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 IRAPISession::CeReadRecordPropsfunction reads the specified set of properties from the current record. If the database was opened with the autoseek flag — that is, if the dwFlagsparameter in the call to IRAPISession::CeOpenDatabasewas set to CEDB_AUTOINCREMENT — then IRAPISession::CeReadRecordPropsincrements the seek pointer by one so that the next call reads the next record in the current sort order. If the database was opened with a sort order active, then IRAPISession::CeReadRecordPropswill 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.

You should 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 of the properties are returned in a single marshaled structure, which consists of an array of CEPROPVALstructures, one for each property requested — or one for each property found if the application set the rgPropIDparameter to NULL when calling the function.

When you are done reading properties, you should free the memory used by the lplpBufferbuffer with a call to IRAPISession::CeRapiFreeBuffer.

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 CEPROPVALstructures 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. Free the pointer returned by this function if the pointer is not NULL.

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 rapi2.h
Library ole32.lib, rapiuuid.lib
Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also