Opening a Database

Windows CE 3.0

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 db 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

Remember that you must mount the volume with CEMountDBVol (if it is not the object store) before opening the database. In addition, the CeOpenDatabaseEx function lets you receive 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 parameters in CENOTIFICATION.

Parameter Description
dwSize Size of the CENOTIFICATION structure
dwParam Application-defined value
uType Why the message was sent
Guid GUID of the relevant database volume
oid Object identifier of the relevant database record
oidParent 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 in CENOTIFYREQUEST, 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 again.

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
  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 version 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"));
      // 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