Programmatically Dismounting Volumes

Article
10/07/2008

To create an unprotected volume in a Hibernate Once/Resume Many environment, you must lock and dismount the volume before you create the hibernation file.

To lock and dismount a volume, you must create an application that calls the DeviceIoControl function. This function sends control codes directly to the file system. By passing the parameters FSCTL_LOCK_VOLUME and FSCTL_DISMOUNT_VOLUME to the function, you can lock and dismount the volume before the hibernation file is created.

Use the following program flow to lock and dismount a volume, and then hibernate the system. The application must also support unlocking the volume when the system boots from the hibernation file.

To programmatically Dismount Volumes

Create an application to lock and dismount a volume you do not want protected by EWF. Use the DeviceIoControl function with the dwIoControlCode parameter FS_LOCK_VOLUME. This locks the volume. If there is an open file handle to the volume when this function is called, the volume fails to lock. By locking the volume before you dismount it, you can ensure that the volume is dismounted cleanly. For example:
```
DeviceIoControl(
     hDevice,
     FSCTL_LOCK_VOLUME,
     NULL,
     0,
     NULL,
     0,
     &cbReturned,
     NULL
     )
```
For more information, see DeviceIOControl and FSCTL_LOCK_VOLUME in the MSDN library.
After the volume is locked, the volume can be dismounted. In your application, call the DeviceIoControl function with the dwIoControlCode parameter FSCTL_DISMOUNT_VOLUME to dismount the volume. This parameter dismounts the volume from the file system. If you do not lock the volume before you dismount it, any open file handles are invalidated and the volume forcibly dismounts.

After the volume is dismounted, any information in the write cache about the volume is flushed, and you can safely write the hibernation file.

For example, call the DeviceIoControl function with the following values:
```
DeviceIoControl(
     hDevice,
     FSCTL_DISMOUNT_VOLUME,
     NULL,
     0,
     NULL,
     0,
     &cbReturned,
     NULL
     )
```
For more information, see DeviceIOControl in the MSDN library.
After the volume is dismounted, create the hibernation file and shut down the system.

Use the SetSuspendState function of the Windows SDK. For example,
```
SetSuspendState ( 
     Hibernate,
     ForceCritical,
     DisableWakeEvent ) 
```
For more information, see SetSuspendState in the Windows SDK.

-Or-

You can use the power management functions included with Windows XP Embedded, for example:
```
XPE_Hibernate( 
     bForceState 
);
```
To use the power management functions, your run-time image requires the following files: Xpepm.dll, Xpepm.lib, and Xpepm.h. All three files are located in the VALUEADD\MSFT\XPEPM folder on Disk 1 of the product media.

For more information, see Power Management APIs.
After the system hibernates, boot the system. The system resumes from the hibernation file.
To allow the system to rediscover the volume, the volume first must be unlocked immediately after the system boots. . Use the DeviceIoControl function with the dwIoControlCode parameter FS_UNLOCK_VOLUME. This unlocks the volume.
```
DeviceIoControl(
     hDevice,
     FSCTL_UNLOCK_VOLUME,
     NULL,
     0,
     NULL,
     0,
     &cbReturned,
     NULL
     )
```
For more information, see DeviceIOControl and FSCTL_UNLOCK_VOLUME in the MSDN library.

After the volume is unlocked, the system automatically rediscovers the volume and makes it accessible. Because the hibernation file does not include any information about the volume, you must unlock the volume on every reboot.

For more information and sample code for dismounting a volume, see Dismounting Volumes in a Hibernate Once/Resume Many Configuration.

Programmatically Dismounting Volumes

See Also

Additional resources