CeMountDBVolEx (EDB) (Windows CE 5.0)
This function is used to mount a volume.
This function does not work with CEDB databases. For more information about CEDB, see CEDB Reference.
BOOL CeMountDBVolEx(PCEGUIDpGuid,LPWSTRlpwszDBVol,CEVOLUMEOPTIONS*pOptions,DWORDdwFlags);
Parameters
- pGuid
[out] A pointer to a buffer that is filled in with a CEGUID to represent the mounted database. - lpwszDBVol
[in] A 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 LAN. - pOptions
[in] A pointer to a CEVOLUMEOPTIONS (EDB) structure. This structure contains various options that affect the behavior and performance of a newly mounted volume. If the volume is already mounted, these options are ignored. If NULL is passed in, then the system defaults are used. For more information, see Configurable EDB Volume Options. - dwFlags
[in] A flag that determines how the database volume is opened. It is one of the flags listed in the following table:dwFlags Option Description CREATE_NEW Creates a new database volume. The function fails if the specified database volume already exists. CREATE_ALWAYS Creates a new database volume. The function overwrites the database volume if it exists. OPEN_EXISTING Opens the database volume. The function fails if the database volume does not exist. OPEN_ALWAYS Opens the database volume if it exists. If the database volume does not exist, the function creates the database volume as if CREATE_NEW were specified. TRUNCATE_EXISTING Opens the database volume. Once opened, the database volume is truncated so that its size is 20 KB. The function fails if the database volume does not exist.
Return Values
TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. The following table lists possible values returned by GetLastError:
| Return Value | Description |
|---|---|
| ERROR_INVALID_PARAMETER | Indicates one of the following:
|
| ERROR_BAD_FORMAT | Indicates that the volume specified is from a different version of EDB. |
| ERROR_FILE_NOT FOUND | Indicates that TRUNCATE_EXISTING is specified and the volume does not exist. |
| ERROR_ACCESS_DENIED | Indicates one of the following:
|
| ERROR_WRONG_PASSWORD | Indicates that the password pOptions->pwszPassword is incorrect. |
| ERROR_ALREADY_EXISTS | Indicates that the function has succeeded and the error is returned from GetLastError if OPEN_ALWAYS or CREATE_ALWAYS was specified, and the database file existed before the call to this function. |
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 will have 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 hits zero, the volume is closed and unmounted. Therefore, the same 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, the CeFlushDBVol (EDB) function can be used to force any pending changes that have been made to a database in the volume to disk. However, calling the CeFlushDBVol function 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. For more information, see Configurable EDB Volume Options.
Once a volume is mounted the volume options (pOptions) cannot be changed. Therefore, volume options are respected only when a volume is mounted for the first time. Subsequent mounts of the volume will succeed, but if incompatible options are specified, then a call to GetLastError returns ERROR_INVALID_PARAMETER.
The following list highlights the differences between this function and the CEDB equivalent function:
- EDB allows specific volume-based options to be set via 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. There are resources consumed while a volume is mounted, and so to improve performance, clients should reduce the time that a volume is mounted. Conversely, it is also expensive to mount a volume, so effort should be made to reduce the number of times you mount a volume.
- 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. The function fails if the TRUNCATE_EXISTING flag is used and the volume does not already exist.
Requirements
OS Versions: Windows CE 5.0 and later.
Header: Windbase.h.
Link Library: Coredll.lib.
See Also
CeFlushDBVol (EDB) | CeUnmountDBVo (EDB)l | CEVOLUMEOPTIONS (EDB) | Configurable EDB Volume Options
Send Feedback on this topic to the authors