Reading a Record

Windows CE 3.0

Once a record is found, call the CeReadRecordPropsEx function to read the properties of the record. To indicate the properties to be read, specify an array of property identifiers. Also, specify the buffer to which the functions write the property data and the size of the buffer. Setting the CEDB_ALLOWREALLOC flag in the dwFlags parameter instructs Windows CE to reallocate the buffer if the returned data is too large. If the database is stored in a compressed format, the database engine must decompress records in 4-KB sections as they are read.

The CeReadRecordPropsEx function can return selected record properties or a full view of all of the properties. You can have CeReadRecordPropsEx allocate memory from the local heap to return the record values. The CeReadRecordPropsEx function can use any heap to return record values, not just the local heap. For efficiency, your application should read all of the desired properties in a single call, instead of in several separate calls.

If you do read for a specific property, check for the CEDB_PROPNOTFOUND flag in the CEPROPVAL structure for that property. You should check for this flag because the record in question might not have the property that you are looking for.

When Windows CE reads a record property successfully, the system copies the property information into the specified buffer as an array of CEPROPVAL structures. The CeReadRecordPropsEx function returns the Windows CE object identifier of the record. All of the variable-size data, such as strings and binary large objects (BLOBs), is copied to the end of the buffer. The CEPROPVAL structures contain pointers to this data.

The following code example shows how to create and write four properties: a 16-bit signed integer, a 32-bit signed integer, a null-terminated string, and a BLOB to the new record.

void ReadingDBRecords (void)
  CEOID CeOid;            // Object identifier of the record read
  PCEGUID pceguid;        // Pointer to the mounted database volume
  WORD wcPropID;          // Number of properties retrieved
  DWORD dwcbBuffer,       // Count of bytes of the *lpBuffer
        dwError;          // Return value of the GetLastError function
  TCHAR szMsg[100];       // String for displaying the error message
  LPBYTE lpBuffer = NULL; // Pointer to a buffer that receives record-
                          // property data
  HANDLE hDataBase,       // Handle to a database to be opened
         hHeap;           // Handle to the heap for allocating records

  // Assign to pceguid the GUID of the mounted volume
  // in which the database resides.
  // ...

  // Create the heap by calling HeapCreate to allocate the database
  // records.
  // ...

  // Open the database with the current seek position to be
  // incremented automatically with each call.

  hDataBase = CeOpenDatabaseEx (
          pceguid,            // Pointer to the mounted volume
          &CeOid,             // Location of the database identifier
          TEXT("MyDBase"),    // Database name
          0,                  // Sort order; 0 indicates to ignore.
          CEDB_AUTOINCREMENT, // Automatically increase seek pointer
          NULL);              // Does not need to receive notification

  // Check for errors on the hDataBase handle before continuing.

  if (hDataBase == INVALID_HANDLE_VALUE)
    // Your error-handling code goes here.

  while ((CeOid = CeReadRecordPropsEx (
            hDataBase,          // Handle of the database.
            CEDB_ALLOWREALLOC,  // Use LocalAlloc to get the buffer.
            &wcPropID,          // Number of properties retrieved
            NULL,               // NULL means retrieve all properties.
            &lpBuffer,          // Buffer receives property data.
            &dwcbBuffer,        // Count of bytes in *lpBuffer.
            hHeap)) != 0)       // Handle to the heap for allocating
                                // the record when
                                // CEDB_ALLOWREALLOC is specified.
    // The record is now available in the lpBuffer. Add code here to
    // manipulate the properties in this record.
    // ...

  // Error handling if CeReadRecordPropsEx fails

  dwError = GetLastError ();

  if (dwError == ERROR_NO_MORE_ITEMS)
    wsprintf (szMsg,
              TEXT("Read through all records in the database."));
  else if (dwError == ERROR_INSUFFICIENT_BUFFER)
    wsprintf (szMsg,
              TEXT("Re-allocation of database records failed."));
    wsprintf (szMsg, TEXT("Other errors."));

  // Close the database handle.

  CloseHandle (hDataBase);

} // End of ReadingDBRecords example code