Database Volumes

Database volumes allow property databases to be created outside the Object Store on devices such as storage cards. A property database is an integrated part of the object store—each record has its own OID. To replicate this behavior in other storage devices, a file (a "database volume") needs to be created, and one or more property databases will be created in that file. Database volumes usually have a CDB extension.

Since database volumes are simply files, the user cannot use Explorer to view the databases in the volume. CDB files are not necessarily hidden and can be deleted by a user. Microsoft Pocket Access can be used to open a CDB file and view the contents.

Database volumes need to be "mounted" before the databases in the volume can be accessed. Finally, when all the databases are closed, the database volume should be unmounted.

Creating and Mounting Database Volumes

The function CEMountDBVol is used both to create new volumes and to open existing volumes. Listing 4.1 shows how to create a new database volume and mount the volume on a storage device called "Storage Card."

Listing 4.1. Creates a database volume

void Listing4_1()
{
  CEGUID pceguid;
  if(!CeMountDBVol(&pceguid,
          _T("\Storage Card\MyVolume.CDB"),
          CREATE_NEW))
    cout ≪ _T("Could not create database volume")
         ≪ endl;
  else
    cout ≪ _T("Database volume created") ≪ endl;
 }

The first argument, pceguid, is used to return a CEGUID value that is used to reference the newly created and mounted database volume. The CEGUID data type is a structure that contains four DWORD values, and although superficially similar to the GUID (Globally Unique Identifier) used in COM and ActiveX (see Chapter 14), its use is restricted to Windows CE databases.

The constant values and semantics for dwFlags are the same as the dwCreationDisposition parameter used when opening and creating files using CreateFile (see Chapter 2). You need to take care when using CREATE_ ALWAYS and TRUNCATE_EXISTING since all databases in an existing volume can be deleted.

• CREATE_NEW—Create a new volume, fail if the volume already exists.

• CREATE_ALWAYS—Create a new volume, overwriting the volume if it already exists.

• OPEN_EXISTING—Open an existing volume, and fail if the volume does not exist.

• OPEN_ALWAYS—Open an existing volume, and if it does not exist, create the volume.

• TRUNCATE_EXISTING—Open an existing volume and empty the contents. Fail if the volume does not exist.

You can call GetLastError to determine the error code if the call to CEMountDBVol fails. If the function fails, pceguid will contain an invalid value. This can be tested using the CHECK_INVALIDGUID macro, which takes a pointer to the CEGUID.

if (CHECK_INVALIDGUID(&pceguid))
    cout ≪ _T("Invalid CEGUID");
else
    cout ≪ _T("Valid CEGUID");

Mounting an existing volume simply requires changing the dwFlags value:

CeMountDBVol(&pceguid,
    _T("\Storage Card\MyVolume.CDB"),
    OPEN_EXISTING);

Unmounting a Volume

You will need to unmount the database volume by calling CeUnmountDBVol once you have finished accessing databases in the volume.

if(!CeUnmountDBVol(&peceguid))
  cout ≪ _T("Volume unmounted");
else
  cout ≪ _T("Volume could not be unmounted");

A reference count is maintained for each volume, and this is incremented whenever an application mounts the volume. The volume is only unmounted when the reference count returns to zero, which happens when the last application unmounts the volume.