Device Events (IoEvent.h)

Applications, including services, can register to receive notification of device events. For example, a catalog service can receive notice of volumes being mounted or dismounted so it can adjust the paths to files on the volume. The system notifies an application that a device event has occurred by sending the application a WM_DEVICECHANGE message. The system notifies a service that a device event has occurred by invoking the service's event handler function, HandlerEx.

To receive device event notices, call the RegisterDeviceNotification function with a DEV_BROADCAST_HANDLE structure. Be sure to set the dbch_handle member to the device handle obtained from the CreateFile function. Also, set the dbch_devicetype member to DBT_DEVTYP_HANDLE. The function returns a device notification handle. Note that this is not the same as the volume handle.

When your application receives notification, if the event type is DBT_CUSTOMEVENT, you may have received one of the device events defined in IoEvent.h. To determine if one of these events has occurred, use the following steps.

1. Treat the event data as a DEV_BROADCAST_HDR structure. Verify that the dbch_devicetype member is set to DBT_DEVTYP_HANDLE.
2. If dbch_devicetype is DBT_DEVTYP_HANDLE, the event data is really a pointer to a DEV_BROADCAST_HANDLE structure.
3. Compare the dbch_eventguid member to the GUIDs listed in the following table using the IsEqualGUID function.

GUID_IO_CDROM_EXCLUSIVE_LOCK

bc56c139-7a10-47ee-a294-4c6a38f0149a

The CD-ROM device has been locked for exclusive access.

Windows Server 2003 and Windows XP: Support for this value requires IMAPI 2.0. For more information, see Image Mastering API.

GUID_IO_CDROM_EXCLUSIVE_UNLOCK

a3b6d27d-5e35-4885-81e5-ee18c00ed779

A CD-ROM device that was locked for exclusive access has been unlocked.

Windows Server 2003 and Windows XP: Support for this value requires IMAPI 2.0. For more information, see Image Mastering API.

GUID_IO_DEVICE_BECOMING_READY

d07433f0-a98e-11d2-917a-00a0c9068ff3

Media spin-up is in progress.

GUID_IO_DEVICE_EXTERNAL_REQUEST

d07433d0-a98e-11d2-917a-00a0c9068ff3

There are several possible causes for this event; for more information, refer to the T10 MMC specification of the GET EVENT STATUS NOTIFICATION Command.

GUID_IO_MEDIA_ARRIVAL

d07433c0-a98e-11d2-917a-00a0c9068ff3

Removable media has been added to the device. The dbch_data member is a pointer to a CLASS_MEDIA_CHANGE_CONTEXT structure. The NewState member provides status information. For example, a value of MediaUnavailable indicates that the media is not available (for example, due to an active recording session).

Windows XP: The dbch_data member is a ULONG value that represents the number of times that media has been changed since system startup.

GUID_IO_MEDIA_EJECT_REQUEST

d07433d1-a98e-11d2-917a-00a0c9068ff3

The removable media's drive has received a request from the user to eject the specified slot or media.

GUID_IO_MEDIA_REMOVAL

d07433c1-a98e-11d2-917a-00a0c9068ff3

Removable media has been removed from the device or is unavailable. The dbch_data member is a pointer to a CLASS_MEDIA_CHANGE_CONTEXT structure. The NewState member provides status information. For example, a value of MediaUnavailable indicates that the media is not available (for example, due to an active recording session).

Windows XP: The dbch_data member is a ULONG value that represents the number of times that media has been changed since system startup.

GUID_IO_VOLUME_CHANGE

7373654a-812a-11d0-bec7-08002be2092f

The volume label has changed.

GUID_IO_VOLUME_CHANGE_SIZE

3a1625be-ad03-49f1-8ef8-6bbac182d1fd

The size of the file system on the volume has changed.

Windows Server 2003 and Windows XP: This value is not supported.

GUID_IO_VOLUME_DISMOUNT

d16a55e8-1059-11d2-8ffd-00a0c9a06d32

An attempt to dismount the volume is in progress. You should close all handles to files and directories on the volume. This event will not necessarily be preceded by a GUID_IO_VOLUME_LOCK event.

GUID_IO_VOLUME_DISMOUNT_FAILED

e3c5b178-105d-11d2-8ffd-00a0c9a06d32

An attempt to dismount a volume failed. This often happens because another process failed to respond to a GUID_IO_VOLUME_DISMOUNT notice by closing its outstanding handles. Because the dismount failed, you may reopen any handles to the affected volume.

GUID_IO_VOLUME_FVE_STATUS_CHANGE

062998b2-ee1f-4b6a-b857-e76cbbe9a6da

The volume's BitLocker Drive Encryption status has changed. This event is signaled when BitLocker is enabled or disabled, or when encryption begins, ends, pauses, or resumes.

Windows Server 2003 and Windows XP: This value is not supported.

GUID_IO_VOLUME_LOCK

50708874-c9af-11d1-8fef-00a0c9a06d32

Another process is attempting to lock the volume. You should close all handles to files and directories on the volume.

GUID_IO_VOLUME_LOCK_FAILED

ae2eed10-0ba8-11d2-8ffb-00a0c9a06d32

An attempt to lock a volume failed. This often happens because another process failed to respond to a GUID_IO_VOLUME_LOCK event by closing its outstanding handles. Because the lock failed, you may reopen any handles to the affected volume.

GUID_IO_VOLUME_MOUNT

b5804878-1a96-11d2-8ffd-00a0c9a06d32

The volume has been mounted by another process. You may open one or more handles to it.

GUID_IO_VOLUME_NAME_CHANGE

2de97f83-4c06-11d2-a532-00609713055a

The volume name has been changed.

GUID_IO_VOLUME_NEED_CHKDSK

799a0960-0a0b-4e03-ad88-2fa7c6ce748a

A file system has detected corruption on the volume. The application should run CHKDSK on the volume or notify the user to do so.

Windows Server 2003 and Windows XP: This value is not supported.

GUID_IO_VOLUME_PHYSICAL_CONFIGURATION_CHANGE

2de97f84-4c06-11d2-a532-00609713055a

The physical makeup or current physical state of the volume has changed.

GUID_IO_VOLUME_PREPARING_EJECT

c79eb16e-0dac-4e7a-a86c-b25ceeaa88f6

The file system is preparing the disc to be ejected. For example, the file system is stopping a background formatting operation or closing the session on write-once media.

Windows Server 2003 and Windows XP: This value is not supported.

GUID_IO_VOLUME_UNIQUE_ID_CHANGE

af39da42-6622-41f5-970b-139d092fa3d9

The volume's unique identifier has been changed. For more information about the unique identifier, see IOCTL_MOUNTDEV_QUERY_UNIQUE_ID.

Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported until Windows Server 2008 R2 and Windows 7.

GUID_IO_VOLUME_UNLOCK

9a8c3d68-d0cb-11d1-8fef-00a0c9a06d32

The volume has been unlocked by another process. You may open one or more handles to it.

GUID_IO_VOLUME_WEARING_OUT

873113ca-1486-4508-82ac-c3b2e5297aaa

The media is wearing out. This event is sent when a file system determines that the error rate on a volume is too high, or its defect replacement space is almost exhausted.

Windows Server 2003 and Windows XP: This value is not supported.

Remarks

The GUID_IO_VOLUME_DISMOUNT and GUID_IO_VOLUME_DISMOUNT_FAILED events are related, as are the GUID_IO_VOLUME_LOCK and GUID_IO_VOLUME_LOCK_FAILED event. The GUID_IO_VOLUME_DISMOUNT and GUID_IO_VOLUME_LOCK events indicate that an operation is being attempted. You should act on the event notification, and record the action taken. The GUID_IO_VOLUME_DISMOUNT_FAILED and GUID_IO_VOLUME_LOCK_FAILED events indicate that the attempted operation failed. You may then use your record to undo the actions you made in response to the operation.

The dbch_hdevnotify member of the DEV_BROADCAST_HANDLE structure indicates the affected device. Note that this is the device notification handle returned by RegisterDeviceNotification, not a volume handle. To perform operations on the volume, map this handle to the corresponding volume handle.

Requirements