CeReadRecordPropsEx (EDB) (Windows CE 5.0)
This function is used to read a set of properties from the current record.
This function does not work with CEDB databases. For more information about CEDB, see CEDB Reference.
CEOID CeReadRecordPropsEx(HANDLEhDbase,DWORDdwFlags,LPWORDlpcPropID,CEPROPID*prgPropID,LPBYTE* lplpBuffer,LPDWORDlpcbBuffer,HANDLEhHeap);
Parameters
- hDbase
[in] A handle to an open database. The handle must be obtained by calling the CeOpenDatabaseInSession (EDB) function. - dwFlags
[in] The read flag, which can be one of the following 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.
0
There are no special instructions for handling the read process.
- lpcPropID
[in/out] A pointer to the number of property IDs in the array, as specified by the prgPropID parameter. If prgPropID is NULL, this parameter receives the number of properties retrieved. - prgPropID
[in] A pointer to an array of property IDs for the properties to be retrieved. If this parameter is NULL, this function retrieves all properties in the record. - lplpBuffer
[in/out] A 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 *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
[in/out] Pointer to a variable that contains the size, in bytes, of the buffer specified by the *lplpBuffer parameter. When the CeReadRecordPropsEx 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] A 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 the dwFlags parameter.
Return Values
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 lists possible values returned by GetLastError:
| Return Value | Description |
|---|---|
| ERROR_INVALID_PARAMETER | Indicates one of the following:
|
| ERROR_INVALID_HANDLE | Indicates that hDatabase is NULL or equal to INVALID_HANDLE_VALUE. |
| ERROR_KEY_DELETED | Indicates that the current row has been deleted. |
| ERROR_NO_MORE_ITEMS | Indicates that the database is not currently positioned on a row. |
| ERROR_NOT_ENOUGH_MEMORY | Indicates that a memory allocation failed. |
| ERROR_INSUFFICIENT_BUFFER | Indicates that dwFlags does not contain the CEDB_ALLOWREALLOC flag, and the length supplied in lpcbBuffer is not large enough to hold the set of properties being read. In this case, on return, *lpcbBuffer will contain the correct size of the buffer needed to read the properties. |
| ERROR_NO_DATA | Indicates that none of the requested properties were found in the record. |
| ERROR_SHARING_VIOLATION | Indicates a lock conflict. |
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, then 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 row (first row if a sort order is present). If CEDB_AUTOINCREMENT was not specified, then the seek pointer is not positioned on a row and the user must call the CeSeekDatabaseEx function before reading a record.
You should read all of the properties you need from the record in a single call. All of 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 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 the function fails, it may have allocated memory on behalf of the caller. You must free the pointer returned by this function if the pointer is not NULL.
The following list highlights the differences between this function and the CEDB equivalent function:
- EDB has a new property type called CEVT_STREAM. CEVT_STREAM is treated like a CEVT_BLOB type when calling the CeReadRecordProps (EDB) function. The data for a CEVT_STREAM property is returned in the CEPROPVAL::val.blob member. Stream properties can be very large, and 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, you should not use this function to read it. Instead you should use the CeOpenStream (EDB) and CeStreamRead (EDB) functions.
Requirements
OS Versions: Windows CE 5.0 and later.
Header: Windbase.h.
Link Library: Coredll.lib.
See Also
CeOpenDatabaseInSession (EDB) | CeOpenStream (EDB) | CeStreamRead (EDB) | CeSeekDatabaseEx (EDB)
Send Feedback on this topic to the authors