Enumerating a Database and Database Volumes

Enumerating databases is the process of sequentially accessing each database in a group. The group can include all databases in the object store, databases of a specified type, or databases in all mounted volumes. Use enumeration when you need to change all databases of a certain type or when you need to synchronize data between a desktop computer and a Windows CE–based device.

Use the CeFindFirstDatabaseEx and CeFindNextDatabaseEx functions to enumerate databases within a specified database volume. The volume can be the object store or any mounted database volume. The primary difference between these two sets of functions is that CeFindFirstDatabaseEx and CeFindNextDatabaseEx have an additional parameter identifying the CEGUID of the volume. If you pass in an invalid CEGUID, Windows CE searches all of the volumes on a Windows CE–based device, including the object store. You can also enumerate the mounted database volumes with a call to CeEnumDBVol.

When you are finished, call CloseHandle to close the enumeration handle.

The following code example shows how to enumerate the databases within the object store.

void EnumeratingDBs (void)
{
  DWORD dwError;          // Return value of GetLastError function.
  TCHAR szMsg[100];       // String to display error message
                          // and database data.
  HANDLE hEnumDB;         // Handle to a database enumerator.
  CEOID CeOid;            // Object identifier of a database.
  CEOIDINFO CeObjectInfo; // Structure that contains
                          // database data.
  PCEGUID pceguid = NULL; // Pointer to the mounted volume identifier.
                          // NULL means all mounted database volumes
                          // are to be searched.

  // Find the first database. Set the database type to 0, so all types
  // of databases are enumerated. If pceguid is set to NULL or an
  // invalid GUID is created by CREATE_INVALIDGUID, all mounted
  // database volumes are searched.

  hEnumDB = CeFindFirstDatabaseEx (pceguid, 0);

  if (hEnumDB == INVALID_HANDLE_VALUE)
  {
    if (GetLastError () == ERROR_OUTOFMEMORY)
      wsprintf (szMsg, TEXT("Out of memory."));
    else
      wsprintf (szMsg, TEXT("Unknown error."));

    return;
  }

  while ((CeOid = CeFindNextDatabaseEx (hEnumDB, pceguid)) != 0)
  {
    // Retrieve database data.
    if (!CeOidGetInfoEx (pceguid, CeOid, &CeObjectInfo))
    {
      // Your error-handling code goes here.

      CloseHandle (hEnumDB);  // Close the search handle.

      return;
    }
    else
    {
      wsprintf (szMsg, TEXT("The name of the database is: %s"),
                  CeObjectInfo.infDatabase.szDbaseName);
    }
  }

  // Error handling if CeFindNextDatabaseEx fails
  dwError = GetLastError ();

  if (dwError == ERROR_KEY_DELETED)
  {
    // A database has been deleted during enumeration. You must
    // restart the enumeration process.
    wsprintf (szMsg,
              TEXT("A database was deleted during enumeration."));
  }
  else if (dwError == ERROR_NO_MORE_ITEMS)
  {
    wsprintf (szMsg, TEXT("No more item to enumerates."));
  }
  else
  {
    wsprintf (szMsg, TEXT("Unknown error."));
  }

  // Close the search handle.
  CloseHandle (hEnumDB);

} // End of EnumeratingDBs example code