Opening a Database

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

Use the CeOpenDatabaseEx (CEDB) function to open a database. CeOpenDatabaseEx specifies the sort order for the database for the session in the propid parameter. To use a different sort order, 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 (CEDB) structure. Windows Embedded CE sends messages to the specified window when other processes or other threads modify the open database. When a change occurs, Windows Embedded CE sends a WM_DBNOTIFICATION message with the lParam set to CENOTIFICATION. The following table describes the possible values of the uType member of the CENOTIFICATION structure.

CeOpenDatabaseEx can also be used to retrieve additional data about other processes and threads from CENOTIFYREQUEST. With CENOTIFYREQUEST, you can choose either the original Windows Embedded 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 members of CENOTIFICATION.

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

The following code example shows how to open an address database by calling CeOpenDatabaseEx. If the database does not exist, the application calls the CeCreateDatabaseEx (CEDB) 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 of the database identifier.
         TEXT("MyDBase"), // Database name.
         0, // Sort order; zero 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;
   }
}

See Also

Concepts

CEDB Database Support