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 reads a set of properties from the current record.

Syntax 

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

Parameters

hDbase

[in] Handle to an open database. The handle must be obtained by calling the CeOpenDatabaseInSession (EDB)function.

dwFlags

[in] The following are possible values:

  • CEDB_ALLOWREALLOC

    The LocalAllocfunction was used to allocate the buffer specified by the ppbBufferparameter. The server can reallocate the buffer if it is not large enough to hold the requested properties.

  • Zero

    There are no special instructions for handling the read process.

lpcPropID

[in, out] Pointer to the number of property IDs in the array, as specified by the prgPropIDparameter. If prgPropIDis set to NULL, this parameter receives the number of properties retrieved.

prgPropID

[in] Pointer to an array of property IDs for the properties to be retrieved. If this parameter is set to NULL, this function retrieves all properties in the record.

lplpBuffer

[in, out] Pointer to the address of a pointer to a buffer that receives the requested properties. If dwFlagsincludes the CEDB_ALLOWREALLOC flag, the buffer can be reallocated if necessary, even if the function fails. If the CEDB_ALLOWREALLOC flag is specified and * lplpBufferis 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

[in, out] Pointer to a variable that contains the size, in bytes, of the buffer specified by *lplpBuffer. When this function returns, 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, and CEDB_ALLOWREALLOC was not specified, this parameter can be used to calculate the amount of memory to allocate for the buffer.

hHeap

[in] Handle to an application-created heap to be used when reallocating memory. This parameter is only meaningful if the CEDB_ALLOWREALLOC flag is set in dwFlags.

Return Value

A non-NULL OID indicates success. Zero indicates failure. The OID returned is the OID of the row on which the seek ends. To get extended error information, call GetLastError. The following table shows possible values.

Return Value Description

ERROR_INSUFFICIENT_BUFFER

The dwFlagsparameter does not contain the CEDB_ALLOWREALLOC flag, and the length supplied in lpcbBufferis not large enough to hold the set of properties being read. In this case, on return, * lpcbBufferwill contain the correct size of the buffer needed to read the properties.

ERROR_INVALID_HANDLE

The hDatabaseparameter is set to NULL or equal to INVALID_HANDLE_VALUE.

ERROR_INVALID_PARAMETER

Indicates one of the following:

  • The lpcPropIDparameter is set to NULL.

  • The lplpBufferparameter is set to NULL.

  • The lpcbBufferparameter is set to NULL.

ERROR_KEY_DELETED

The current record has been deleted.

ERROR_NO_DATA

None of the requested properties were found in the record.

ERROR_NO_MORE_ITEMS

The database is not currently positioned on a record.

ERROR_NOT_ENOUGH_MEMORY

A memory allocation failed.

ERROR_SHARING_VIOLATION

The record is locked by another process.

Remarks

Use the CeSeekDatabaseEx (EDB)function to position the database on a record before calling this function.

If the database was opened with CEDB_AUTOINCREMENT, this 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 unpredictable.

If CEDB_AUTOINCREMENT is specified when the database was opened, the seek pointer is positioned on a record, the first record if a sort order is present. If CEDB_AUTOINCREMENT was not specified, the seek pointer is not positioned on a record, and the user must call the CeSeekDatabaseExfunction before reading a record.

Read all properties that you need from a record in a single call. All properties are returned in a single marshaled structure, which consists of an array of CEPROPVALstructures. There is one CEPROPVALstructure for each property requested or, if prgPropIDis NULL, there is one for each property found.

If a variable-length property is requested, such as a CEVT_BLOB, CEVT_LPWSTR, or CEVT_STREAM, it is packed at the end of the returned buffer, and the pointers in the CEPROPVALstructures point into this marshaled buffer. This means that the only memory that must be freed is the original pointer to the buffer passed in to the call or allocated by this function. Even if this function fails, it might have allocated memory. You must free the pointer returned by this function if the pointer is not set to NULL.

The following are the differences between this function and the CEDB equivalent function:

  • EDB has a new property type called CEVT_STREAM. CEVT_STREAM, which is treated like a CEVT_BLOB type when calling this function. The data for a CEVT_STREAM property is returned in the val.blobmember of CEPROPVAL. Stream properties can be very large. If you read a stream property using this function, a large amount of memory may have to be allocated to hold the stream data. If a stream property is large, do not use this function to read it. Instead, use the CeOpenStream (EDB)and the CeStreamRead (EDB)functions.

Requirements

Header windbase.h
Library coredll.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also