CeMountDBVolEx (EDB)

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function mounts a volume.

Syntax

BOOL CeMountDBVolEx(
PCEGUID pGuid,
LPWSTR lpwszDBVol,
CEVOLUMEOPTIONS* pOptions,
DWORD dwFlags
);

Parameters

• pGuid
  [out] Pointer to a buffer that is filled with the CEGUID of the mounted database.

• lpwszDBVol
  [in] Pointer to the null-terminated string that contains the file name and path of the database volume to be mounted. The path is limited to MAX_PATH characters and includes the NULL character. The function can accept any path including Uniform Naming Convention (UNC) names for files on a local area network (LAN).

• pOptions
  [in] Pointer to a CEVOLUMEOPTIONS (EDB) structure that contains settings for the behavior and performance of a newly mounted volume. If the volume is already mounted, these options are ignored. If NULL is passed in, the system defaults are used.

• dwFlags
  [in] Flag that determines how the database volume is opened. The following table shows possible values.

  Value	Description
  CREATE_ALWAYS	Creates a new database volume. This function overwrites the database volume if it exists.
  CREATE_NEW	Creates a new database volume. This function fails if the specified database volume already exists.
  OPEN_ALWAYS	Opens the database volume if it exists. If the database volume does not exist, this function creates the database volume as if CREATE_NEW were specified.
  OPEN_EXISTING	Opens the database volume. This function fails if the database volume does not exist.
  TRUNCATE_EXISTING	Opens the database volume. Once opened, the database volume is truncated to 20 KB. The function fails if the database volume does not exist.

Return Value

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. The following table shows possible values.

Remarks

In EDB, mounting a volume consists of opening the EDB database file. Once a volume is mounted, it is assigned a unique GUID and the volume remains mounted until it is fully unmounted using the CeUnmountDBVol (EDB) function. The volume GUID remains the same as long as the volume is mounted. The same volume has the same GUID across all processes in the system.

Each time the same volume is mounted, a reference count is incremented. When a volume is unmounted, the reference count is decremented. When the reference count reaches zero, the volume is closed and unmounted. Therefore, a volume can be mounted at the same time in different processes and can be mounted multiple times in the same process.

All data written to a mounted database volume is cached until one of the following occurs:

• It is explicitly flushed. For more information, see CeFlushDBVol (EDB).
• It is flushed by a background EDB thread.
• It is unmounted.

Once a database is mounted, CeFlushDBVol can be used to commit pending changes. However, calling CeFlushDBVol is not required because EDB automatically flushes volumes on a background thread every 10 seconds if changes have been made to that volume. The pOptions parameter can be used to configure the flush interval, as well.

Once a volume is mounted the volume options set in pOptions cannot be changed. Therefore, volume options are respected only when a volume is mounted for the first time. Subsequent mounts of the volume succeed, but if incompatible options are specified, a call to GetLastError returns ERROR_INVALID_PARAMETER.

The following are the differences between this function and the CEDB equivalent function:

• EDB allows specific volume-based options to be set with the CEVOLUMEOPTIONS structure. This is not available in CEDB.
• If you specify CREATE_ALWAYS or OPEN_ALWAYS and the file already exists, the function succeeds, but GetLastError returns ERROR_ALREADY_EXISTS. CEDB does not do this. It fails and returns ERROR_ACCESS_DENIED.
• In EDB, a volume remains open as long as it is mounted. Since resources are consumed while a volume is mounted, reduce the time that a volume is mounted to improve performance. It is also expensive to mount a volume, so reduce the number of times you mount a volume as much as possible.
• The TRUNCATE_EXISTING flag truncates an existing volume only if no other thread has the volume open. If the volume is open, this function fails and GetLastError returns ERROR_ACCESS_DENIED. This function fails if the TRUNCATE_EXISTING flag is used and the volume does not already exist.

Requirements

See Also

Reference

EDB Functions
CeFlushDBVol (EDB)
CeUnmountDBVol (EDB)

Other Resources