Commands related to devices and device interfaces
|device_ioctl DEVICEHANDLE IOCTLCODE|
|start_device_notifier SCRIPT ?-deviceinterface DEVICEINTERFACE? ?-handle DEVICEHANDLE?|
This package provides procedures related to device information and management in Windows operating systems.
The device_ioctl command provides thin wrapper around the DeviceIoControl Win32 function. This allows for device specific control commands to be issued to devices. You will need to refer to the Windows SDK documentation for specifics of the ioctls supported by various devices.
Device notifications are generated by Windows to inform applications about changes in device configurations as well as related events. For example, notifications can be used by an application to learn about media change in CD-ROM drives, plugging in of a USB device, mounting a remote share and so on. These notifications allow applications to save any changes and release resources as appropriate.
Notifications are also used by the system to inform applications about pending changes giving them the chance to cancel them.
TWAPI delivers device notifications through callback scripts registered by the application through the start_device_notifier command. Applications must specify the device or device interface class for which they wish to receive notifications and the corresponding script to be invoked to receive them.
|configchangecanceled||A request to change the current dock/undock device configuration was canceled. No additional arguments are present.|
|configchanged||The current device configuration has changed due to docking or undocking. No additional arguments are present.|
|customevent||A custom event defined by a driver. An additional argument may be present if the notifier was created with a -devicehandle option. This provides more detail on the event and has one of the following values: io_volume_change, io_volume_dismount, io_volume_dismount_failed, io_volume_mount, io_volume_lock, io_volume_lock_failed, io_volume_unlock, io_volume_name_change, io_volume_physical_configuration_change, io_volume_device_interface, io_media_arrival, io_media_removal, io_device_becoming_ready, io_device_external_request, io_media_eject_request, io_drive_requires_cleaning, io_tape_erase, io_disk_layout_change. Refer to the Windows SDK and DDK for more information on these.|
|devicearrival||A new device or media has become available. The
first additional argument is one of deviceinterface, handle, port or
volume depending on source of the
If this first argument in deviceinterface, (ie. device interfaces are being monitored (DEVICEINTERFACE is unspecified, an empty string, or a device interface GUID), it is followed by the device interface class GUID for the new device interface, and the device interface class name.
If the value is handle, two additional arguments may be present containing the internal device and notification handles. These should be treated as opaque.
If the value is port, one additional argument, the name of the port, may be present.
If the value is volume, the first additional argument is a list of drive letters corresponding to the new detected volumes (note there may be more than one). This is followed by a list of attributes. If the list includes mediachange, it indicates that new media was inserted (e.g. a CD-ROM); otherwise, it indicates a new physical device (e.g. a USB pen drive). If the list includes networkvolume, it indicates the new volume is accessed over the network.
|devicequeryremove||Request permission to remove a device. The
application can deny the request by returning the string
deny. Any other value will be treated
as an allow. It is important that the script return an answer in
prompt fashion. Any significant processing should be queued for
The arguments are the same as those for devicearrival when the device source type is handle.
Note this notification is only delivered when the -handle option is used. The application can therefore easily use the notifier id to associate the notification with a specific device. If the callback script returns anything other than deny, it should first close all open handles on the device, including the one passed as the argument value for the -handle option. Otherwise, the device removal will fail.
|devicequeryremovefailed||A request to remove a device was canceled, either because an application denied it or there were open handles to the device. Additional arguments are the same as devicequeryremove.|
|deviceremovecomplete||Removal of a device or media has been completed. For physical devices this means the device has been physically disconnected. For volumes, this indicates the volume has been dismounted. Additional arguments are identical to those of devicearrival.|
|deviceremovepending||A device is being removed and not available. Additional arguments are identical to those of devicearrival.|
|devicetypespecific||An event specific to the type of device. Additional arguments are identical to those of devicearrival.|
|devnodes_changed||The system device tree has been modified. Windows does not provide any additional detail about the change and it is up to the application to examine the device tree components of interest.|
|querychangeconfig||Request to change the current dock/undock configuration. The application can allow or deny the request. The command has no additional arguments. See devicequeryremove for more detail on how the script should respond.|
|userdefined||A user defined event sent by an application using BroadcaseSystemMessage. An additional argument specifies the name of the event (vendor defined).|
Copyright © 2008 Ashok P. Nadkarni