Opening a Database (Windows CE 5.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 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
/*
See Also
Send Feedback on this topic to the authors