Opening a Database

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 close the database and open it up again with a different sort order. 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.

Remember that you must mount the volume with CEMountDBVol before opening the database. In addition, CeOpenDatabaseEx lets you receive additional data regarding other processes and threads through CENOTIFYREQUEST. CENOTIFYREQUEST lets you choose either the original Windows CE messages for database changes or the WM_DBNOTIFICATION message. The lParam of WM_DBNOTIFICATION points to a CENOTIFICATION structure. The following table describes the different parameters of the CENOTIFICATION structure.

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, free memory is allocated to CENOTIFICATION with a call to the CeFreeNotification function. You must delete the CENOTIFICATION structure each time you receive a WM_DBNOTIFICATION message.

The following code example attempts to open a database of addressees by calling CeOpenDatabaseEx. If the database does not exist, the code example calls CeCreateDatabaseEx to create a new address database with three different sort orders. After creating the database, the example attempts 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 where 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 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"));
    }
    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 to sort by.
        // 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

/*