Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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.

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 pGuidparameter is set to NULL.

  • The lpwszDBVolparameter is set to NULL.

  • The wVersionmember returned is not equal to CEVOLUMEOPTIONS_VERSION .

  • The dwFlagsmember of CEVOLUMEOPTIONSis used, and one of the values set is not valid.

  • The dwFlagsparameter contains an invalid flag combination.

ERROR_WRONG_PASSWORD

The password pwszPasswordmember of CEVOLUMEOPTIONSis 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, CeFlushDBVolcan be used to commit pending changes. However, calling CeFlushDBVolis not required because EDB automatically flushes volumes on a background thread every 10 seconds if changes have been made to that volume. The pOptionsparameter can be used to configure the flush interval, as well.

Once a volume is mounted the volume options set in pOptionscannot 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 GetLastErrorreturns 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 CEVOLUMEOPTIONSstructure. This is not available in CEDB.

  • If you specify CREATE_ALWAYS or OPEN_ALWAYS and the file already exists, the function succeeds, but GetLastErrorreturns 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 GetLastErrorreturns ERROR_ACCESS_DENIED. This function fails if the TRUNCATE_EXISTING flag is used and the volume does not already exist.

Requirements

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

See Also