Device Events (Windows)

Switch View

Device Events

Device Events

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.

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

Device Event GUID	Meaning
GUID_IO_CDROM_EXCLUSIVE_LOCK	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. Windows 2000: This value is not supported.
GUID_IO_CDROM_EXCLUSIVE_UNLOCK	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. Windows 2000: This value is not supported.
GUID_IO_DEVICE_BECOMING_READY	Media spin-up is in progress. Windows 2000: This value is not supported.
GUID_IO_DEVICE_EXTERNAL_REQUEST	There are several possible causes for this event; for more information, refer to T10 MMC specification of the GET EVENT STATUS NOTIFICATION Command, at http://www.t10.org/. Windows 2000: This value is not supported.
GUID_IO_MEDIA_ARRIVAL	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/2000: 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	The removable media's drive has received a request from the user to eject the specified slot or media. Windows 2000: This value is not supported.
GUID_IO_MEDIA_REMOVAL	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/2000: 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	The volume label has changed.
GUID_IO_VOLUME_CHANGE_SIZE	The size of the file system on the volume has changed. Windows Server 2003 and Windows XP/2000: This value is not supported.
GUID_IO_VOLUME_DISMOUNT	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	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	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/2000: This value is not supported.
GUID_IO_VOLUME_LOCK	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	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	The volume has been mounted by another process. You may open one or more handles to it.
GUID_IO_VOLUME_NAME_CHANGE	The volume name has been changed.
GUID_IO_VOLUME_NEED_CHKDSK	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/2000: This value is not supported.
GUID_IO_VOLUME_PHYSICAL_CONFIGURATION_CHANGE	The physical makeup or current physical state of the volume has changed.
GUID_IO_VOLUME_PREPARING_EJECT	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/2000: This value is not supported.
GUID_IO_VOLUME_UNLOCK	The volume has been unlocked by another process. You may open one or more handles to it.
GUID_IO_VOLUME_WEARING_OUT	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/2000: This value is not supported.

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.

See Also