CeMountDBVolEx (EDB) (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function mounts a volume.

This function does not work with CEDB databases. For more information about CEDB, see CEDB Reference.

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. For more information, see Configurable EDB Volume Options.

  • 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.

Return Value Description

ERROR_ALREADY_EXISTS

This function has succeeded, and OPEN_ALWAYS or CREATE_ALWAYS was specified. The database existed before the call to this function.

ERROR_ACCESS_DENIED

Indicates one of the following:

  • TRUNCATE_EXISTING is specified, and the volume is already mounted or the file cannot be truncated.
  • The volume is read-only.

ERROR_BAD_FORMAT

The volume specified is from a different version of EDB.

ERROR_FILE_NOT FOUND

TRUNCATE_EXISTING is specified, and the volume does not exist.

ERROR_INVALID_PARAMETER

Indicates one of the following:

  • The pGuid parameter is set to NULL.
  • The lpwszDBVol parameter is set to NULL.
  • The wVersion member returned is not equal to CEVOLUMEOPTIONS_VERSION.
  • The dwFlags member of CEVOLUMEOPTIONS is used, and one of the values set is not valid.
  • The dwFlags parameter contains an invalid flag combination.

ERROR_WRONG_PASSWORD

The password pwszPassword member of CEVOLUMEOPTIONS is incorrect.

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.
  • **
  • **

For more information, see Configurable EDB Volume Options.

Requirements

Header Windbase_edb.h
Library coredll.lib
Windows Embedded CE Windows CE 5.0 and later

See Also

Reference

EDB Functions
CeFlushDBVol (EDB)
CeUnmountDBVol (EDB)

Concepts

Configurable EDB Volume Options