Tcl Windows API extension

Device management

Commands related to devices and device interfaces

SYNOPSIS

package require twapi

device_ioctl DEVICEHANDLE IOCTLCODE

start_device_change_monitor SCRIPT ?-deviceinterface DEVICEINTERFACE?

stop_device_change_monitor 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.

Device detection

The commands start_device_change_monitor and stop_device_change_monitor allow monitoring of changes to the device tree, including insertion of CD-ROM's or USB drives.

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_change_monitor SCRIPT ?-deviceinterface DEVICEINTERFACE?: Registers SCRIPT to be invoked when the changes of the specified type occur in the device tree.

The command returns an identifier corresponding to the monitoring callback. When no longer interested in the specified changes, the returned identifier should be passed to stop_device_change_monitor to end the monitoring.

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.

The callback SCRIPT is invoked with additional arguments. The first argument indicates the event type an may be one of devnodes_changed, devicearrival, or deviceremovecomplete. (These constants have the same name as in the Windows SDK; refer there for exact semantics).

Event type devnodes_changed indicates that the device tree has been modified. No additional arguments are present that indicate the exact nature of the change.

Event type devicearrival indicates a new device has been detected by the system. If device interfaces are being monitored (DEVICEINTERFACE is unspecified, an empty string, or a device interface GUID), the second argument passed to SCRIPT is devtyp_deviceinterface, the third argument is the device interface class GUID for the new device interface, and the fourth argument is the device interface class name.

When DEVICEINTERFACE was specified as volume, devicearrival events have the second argument devtyp_volume. The third argument is a list of drive letters corresponding to the new detected volumes (note there may be more than one). The fourth argument is 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.

When DEVICEINTERFACE was specified as port, devicearrival events have the second argument devtyp_port. The third argument is the name of the port.

The third event deviceremovecomplete is generated when a device is remove from the system. The additional arguments are identical to those for devicearrival.
stop_device_change_monitor MONITORID: Cancels monitoring of device changes. MONITORID which must be an identifier previously returned by start_device_change_monitor.