Device management

Commands related to devices and device interfaces

SYNOPSIS

package require twapi

device_ioctl DEVICEHANDLE IOCTLCODE

start_device_notifier SCRIPT ?-deviceinterface DEVICEINTERFACE? ?-handle DEVICEHANDLE?

stop_device_notifier MONITORID

DESCRIPTION

This package provides procedures related to device information and management in Windows operating systems.

Device ioctls

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

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.

Commands

device_ioctl DEVICEHANDLE IOCTLCODE

This is a thin wrapper around the Win32 DeviceIoControl function. Primary role of the wrapper is to do automatic output buffer management for the caller. DEVICEHANDLE, usually obtained through create_file, is a handle to the device of interest. IOCTLCODE is the IOCTL code to be sent to the device. The command returns the result as a Tcl binary value that should in general be parsed with the Tcl binary scan command.

start_device_notifier SCRIPT ?-deviceinterface DEVICEINTERFACE? ?-handle DEVICEHANDLE?

Registers SCRIPT to be invoked when the events are generated from a specified device class or device.

The command creates a new notifier and returns its identifier. When no longer interested in the specified changes, the returned identifier should be passed to stop_device_notifier to stop the notifications and release associated resources.

If no additional options were specified to the command, or if the -deviceinterface option was specified with DEVICEINTERFACE as an empty string, all device interfaces are monitored. If DEVICEINTERFACE is one of the keywords port or volume, then all ports and all volumes respectively are monitored. Otherwise, DEVICEINTERFACE must be the GUID for a particular device interface class, and only that interface class is monitored. Refer to the Windows SDK for a list of GUIDs for various device interface classes.

If the -handle option is specified, DEVICEHANDLE must be a handle to a resource on the device obtained through either create_file or get_tcl_channel_handle. In this case, only event notifications from that particular device are passed to the callback script.

At most one of the options -deviceinterface and -handle can be specified.

The callback SCRIPT is invoked with additional arguments. The first argument is the id of the notifier that was returned by this command. The second argument is the event notification type and may be followed by additional arguments specific to the type.

For compatibility with future releases, the callback script should ignore notification types not listed below. For the same reason, it should also ignore any additional arguments or unexpected values for listed arguments.

Certain event types require the callback script to return a value. These are noted below.

The notification type and the corresponding arguments are shown in the table below. The symbols match exactly the DBT_* symbols defined in the Windows SDK except for the character case and prefix. For example, devicearrival corresponds to DBT_DEVICEARRIVAL. More detail about each event can be obtained by looking at the SDK documentation for the corresponding symbol.

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 notification. 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 later. 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).

This command requires a threaded build of Tcl and will raise an exception on non-threaded builds.

stop_device_notifier MONITORID

Cancels monitoring of device changes. MONITORID which must be an identifier previously returned by start_device_notifier.

COPYRIGHT

Copyright © 2008 Ashok P. Nadkarni