CeReadRecordPropsEx (EDB) (Windows Embedded CE 6.0)

1/6/2010

This function reads a set of properties from the current record.

This function does not work with CEDB databases. For more information about CEDB, see CEDB Reference.

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 LocalAlloc function was used to allocate the buffer specified by the ppbBuffer parameter. 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 prgPropID parameter. If prgPropID is 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 dwFlags 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 *lplpBuffer 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
  [in, out] Pointer to a variable that contains the size, in bytes, of the buffer specified by *lplpBuffer. When this function 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] 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.

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 CeSeekDatabaseEx function 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 CEPROPVAL structures. There is one CEPROPVAL structure for each property requested or, if prgPropID is 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 CEPROPVAL structures 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.blob member 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

See Also

Reference

EDB Functions
CeOpenDatabaseInSession (EDB)
CeOpenStream (EDB)
CeStreamRead (EDB)
CeSeekDatabaseEx (EDB)