Opening a Database (Windows CE 5.0)

Article
09/14/2012

Once you create a database, use the CeOpenDatabaseEx function to open it. CeOpenDatabaseEx specifies the sort order you use on the database during a given session in the propid parameter. To use a different sort order, you must open the database again with a different sort order specified. If no sort order is specified, the order of records is undefined.

You can also pass a handle to a window in the hwndNotify member of the CENOTIFYREQUEST structure. Windows CE sends messages to the specified window when other processes or other threads modify the open database. When a change occurs, Windows CE sends a WM_DBNOTIFICATION message with the lParam set to CENOTIFICATION. The following table describes the possible values of the uType parameter in the CENOTIFICATION structure.

Message	Description
DB_CEOID_CHANGED	Record changed.
DB_CEOID_CREATED	Record created.
DB_CEOID_RECORD_DELETED	Record deleted.

**Note **You must mount the volume with CeMountDBVol, if it is not the object store, before opening the database.

The CeOpenDatabaseEx function can also be used to retrieve additional data about other processes and threads through the CENOTIFYREQUEST structure. CENOTIFYREQUEST lets you choose either the original Windows CE messages for database changes or the WM_DBNOTIFICATION message. The lParam field of WM_DBNOTIFICATION points to a CENOTIFICATION structure.

The following table describes the different members in CENOTIFICATION.

Member	Description
dwSize	The size of the CENOTIFICATION structure.
dwParam	The application-defined value.
uType	Why the message was sent.
guid	The GUID of the relevant database volume.
oid	The object identifier of the relevant database record.
oidParent	The object identifier of the parent of the relevant database record.

Windows CE places CENOTIFICATION in a heap that you define in CENOTIFYREQUEST. If you do not specify a heap, Windows CE creates the heap in your default process heap. Once finished, the memory allocated to CENOTIFICATION must be freed with a call to the CeFreeNotification function. You must free the CENOTIFICATION structure each time you receive a WM_DBNOTIFICATION message.

The following code example shows how an application opens an address database by calling the CeOpenDatabaseEx function. If the database does not exist, the application calls CeCreateDatabaseEx function to create a new address database that has four different sort orders. After creating the database, the application again calls CeOpenDatabaseEx to open the database.

HANDLE OpenDatabase (
      HWND hwndNotify,  // Handle to the window to which
                        // notification messages are posted
      PCEGUID pceguid,  // Pointer to the mounted database
                        // volume in which the database to
                        // be opened resides
      CEOID CeOid)      // Object identifier of the database
                        // to be opened
{
  int index;
  DWORD dwError;              // Return value from GetLastError
  HANDLE hDataBase;           // Open handle to the address database
  CENOTIFYREQUEST *pRequest;  // CENOTIFYREQUEST structure
  CEDBASEINFO CEDBInfo;       // Structure containing the 
                              // database data
  TCHAR szError[100];         // String to use with error messages

  // Allocate memory for pRequest.
  pRequest = (CENOTIFYREQUEST *) LocalAlloc (LPTR,
                                        sizeof (CENOTIFYREQUEST));

  pRequest->dwSize = sizeof (CENOTIFYREQUEST);
  pRequest->hwnd = hwndNotify;
  pRequest->hHeap = NULL; // Let system allocate memory properly.
  pRequest->dwFlags = 0;  // Notifications are handled as they
                          // were in Windows CE 1.0.

  hDataBase = CeOpenDatabaseEx (
          pceguid,            // Pointer to the mounted volume
          &CeOid,             // Location for the database identifier
          TEXT("MyDBase"),    // Database name
          0,                  // Sort order; 0 indicates to ignore
          CEDB_AUTOINCREMENT, // Automatically increase seek pointer
          pRequest);          // Pointer to a CENOTIFYREQUEST
                              // structure

  if (hDataBase == INVALID_HANDLE_VALUE)
  {
    dwError = GetLastError ();

    if (dwError == ERROR_NOT_ENOUGH_MEMORY)
    {
      wsprintf (szError, TEXT("Not enough memory"));
    }
    else
    {
      // Possibility of nonexisting database; create it.

      // Initialize structure CEDBInfo
      memset (&CEDBInfo, 0, sizeof(CEDBInfo));

      // Create the database with the following specified flags.
      // Create the database as uncompressed.
      // You can use CeSetDataBaseInfoEx to compress the database.
      CEDBInfo.dwFlags =
          CEDB_VALIDNAME        // szDbaseName is valid
          | CEDB_VALIDTYPE      // dwDbaseType is valid
          | CEDB_VALIDDBFLAGS   // HIWORD of dwFlag is valid
          | CEDB_VALIDSORTSPEC  // rgSortSpecs is valid
          | CEDB_NOCOMPRESS;    // The database is not compressed.

      // Assign the database name as MyDBase.
      wcscpy (CEDBInfo.szDbaseName, TEXT("MyDBase"));

      // Assign the database type.
      CEDBInfo.dwDbaseType = 0;

      // Set the number of active sort orders to 4.
      // This is the maximum number allowed.
      CEDBInfo.wNumSortOrder = 4;

      // Initialize the array of sort-order descriptions.
      for (index = 0; index < CEDBInfo.wNumSortOrder; ++index)
      {
        // Sort in descending order.
        CEDBInfo.rgSortSpecs[index].dwFlags = CEDB_SORT_DESCENDING;

        // Assign the identifier of the properties by which to sort.
        // CEDBInfo.rgSortSpecs[index].propid = ...;
      }

      // Create database "MyDBase".
      CeOid = CeCreateDatabaseEx (pceguid, &CEDBInfo);

      if (CeOid == NULL)
      {
        wsprintf (szError,
                  TEXT("ERROR: CeCreateDatabaseEx failed (%ld)"),
                  GetLastError ());
      }
      else  // Succeeded in creating the database; open it.
      {
        hDataBase = CeOpenDatabaseEx (pceguid, &CeOid,
                          TEXT("MyDBase"), 0, 0, pRequest);
      }
    }
  }

  // Return the database handle.
  return hDataBase;

} // End of OpenDatabase example code

/*

Share via

Opening a Database (Windows CE 5.0)

See Also

Additional resources