Device management

Commands related to devices and device interfaces

SYNOPSIS

package require twapi_device

device_ioctl DEVICEHANDLE IOCTLCODE ?-outputcount BUFSIZE?

eject DEVICE

eject_media DEVICE

find_physical_disks

get_physical_disk_info DISK ?options?

load_media DEVICE

lock_media DEVICE

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

stop_device_notifier MONITORID

unlock_media DEVICE

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.

Media control

The commands eject_media, load_media and lock_media and unlock_media provide control over removable devices and media.

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.

Physical disks

The find_physical_disks command returns the list of physical disks installed in the system. The get_physical_disk_info command can then be used to retrieve detailed information about the physical disk.

Commands

device_ioctl DEVICEHANDLE IOCTLCODE ?-outputcount BUFSIZE?

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 -outputcount option should be specified if the call is expected to return data. BUFSIZE should be the size of the output buffer expected by the call. The command will then return the result as a Tcl binary value that should in general be parsed with the Tcl binary scan command.

eject DEVICE

Alias for eject_media.

eject_media DEVICE

Ejects a removable device, such as a CD-ROM or pen drive. DEVICE should be of the form X:, X:\, X:/ where X is a drive letter, or a physical disk path as returned by the find_physical_disks command, or cdrom, in which case the first CD-ROM in the device list is ejected.

find_physical_disks

Returns the list of physical disks in the system. The returned paths can be passed to CreateFile or create_file to get a handle to the raw physical disk.

get_physical_disk_info DISK ?options?

Returns information about a physical disk. DISK is a device path to the physical disk in the format returned by find_physical_disks. The command returns a keyed list with fields depending on the passed options:

-all	Returns all fields.
-geometry	Returns the geometry of the disk. The value is itself a keyed list with the fields -cylinders, -mediatype, -trackspercylinder, -sectorspertrack and -bytespersector.
-layout	Returns the layout of the disk in terms of how it is partitioned. The returned value is a keyed list with the fields depending on how the disk is partitioned. See below for a discussion.

The partitioning of a disk can take several forms and the information returned by the -layout differs in each case. The following is a brief summary that assumes familiarity with disk formats. See the Windows DDK documentation for details.

On Windows 2000, the -layout field value is a keyed list with the fields -partitioncount, -signature and -partitions containing the number of partitions of the disk, the disk signature, and a list of partitions. Each element of the partition list is itself a keyed list with the fields -startingoffset, -partitionlength, -hiddensectors, -partitionnumber, -partitiontype, -bootindicator, -recognizedpartition and -rewritepartition.

On Windows XP and newer operating systems, the -layout field value is a keyed list with the fields, -partitioncount, -partitionstyle and -partitions. If the -partitionstyle field is mbr, an additional field -signature is present. If the -partitionstyle is gpt, three additional fields -startingusableoffset, -usablelength and -maxpartitioncount. Other possible value of -partitionstyle are raw or unknown in which case there are no additional fields. The -partitions field is a list each element of which is itself a keyed list containing information about each partition. Note that the number of elements of the -partitions list may not match the value of the -partitioncount field in case information for some partitions cannot be retrieved. Every element of the -partitions field will have the fields -partitionstyle, -startingoffset, -partitionlength, -partitionnumber and -rewritepartition. In addition, if -partitionstyle is mbr, the element will also have the fields -hiddensectors, -partitiontype, -bootindicator and -recognizedpartition. If -partitionstyle is gpt, it will have the fields -partitiontype, -partitionif, -attributes and -name. Partition styles raw and unknown have no additional fields.

load_media DEVICE

Load removable media such as a CD or DVD. DEVICE should be of the form X:, X:\, X:/ where X is a drive letter, or a physical disk path as returned by the find_physical_disks command, or cdrom, in which case the first CD-ROM in the device list is loaded.

lock_media DEVICE

Locks the media in a device with removable media such as a CD-ROM. On devices that support this function (not all do), locking the media will prevent the media from being ejected. The media can be unlocked with unlock_media. DEVICE should be of the form X:, X:\, X:/ where X is a drive letter, or a physical disk path as returned by the find_physical_disks command, or cdrom, in which case the media in the first CD-ROM in the device list is locked.

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.

unlock_media DEVICE

Unlocks the media in a device with removable media such as a CD-ROM which had been previously locked with lock_media. DEVICE should be of the form X:, X:\, X:/ where X is a drive letter, or a physical disk path as returned by the find_physical_disks command, or cdrom, in which case the first CD-ROM in the device list is unlocked.

COPYRIGHT

Copyright © 2008 Ashok P. Nadkarni