Tcl Windows API extension

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.

Device management

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. The devinfoset command returns a handle to a device information set that contains device elements corresponding to devices in the system. A device element or the entire set can then be retrieved with devinfoset_element and devinfoset_elements respectively. The device instance identifiers for the devices in the set are available through devinfoset_instance_ids. To get properties of a device, such as its description, bus number etc., use devinfoset_element_registry_property. The command rescan_devices forces the device manager to rescan the system for all devices.

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.

device_element FIELD DEVICE_ELEMENT

Returns the specified field from a device element structure. FIELD must be class_guid or device_instance. The former is the GUID of the device's setup class. The latter is an opaque handle to the device's devnode. DEVICE_ELEMENT is an opaque structure containing a device element as returned by the devinfoset_element or devinfoset_elements calls.

devinfoset options

Returns a handle to a device information set containing device elements. The returned handle must be closed by calling devinfoset_close. The included elements depend on the options specified. Without any options, all device elements are included. Otherwise the elements are restricted to those matching one or more of the options in the table below.

-classtype setup\|interface	Specifies whether the GUID specified by the GUID option is that of a device setup class (default) or a device interface class.
-currentprofileonly BOOLEAN	If specified as true, only devices present in the current hardware profile are included in the set. Default is false.
-guid GUID	The GUID for a device setup class or a device interface class depending on the -classtype option. Only devices belonging to the class with that GUID are returned. If unspecified or the empty string, devices from all classes are included in the information set.
-pnpenumerator PNPENUMERATOR	If specified, only devices for that PnP enumerator are returned. PNPENUMERATOR may be the GUID of the enumerator or it symbolic name such as USB, PCI, PCMCIA, SCSI etc. This option can only be used if the -classtype option is setup.
-presentonly BOOLEAN	If specified as true, only devices currently present in the system are included in the set. Default is false.

devinfoset_close HDEVINFOSET

Closes a handle to device information set as returned by devinfoset.

devinfoset_element HDEVINFOSET INSTANCEID

Returns the device element within a device information set corresponding to the device instance identifier INSTANCEID. HDEVINFOSET is a handle to a device information set as returned by devinfoset. Use device_element to extract each field in the element.

devinfoset_element_registry_property HDEVINFOSET DEVICELEM PROPERTY

Returns the value of a registry property for a device element in a device information set. HDEVINFOSET is a handle to a device information set as returned by devinfoset. DEVICEELEMENT is an opaque structure containing a device element as returned by the devinfoset_element or devinfoset_elements calls. PROPERTY is one of the following: devicedesc, hardwareid, compatibleids, service, class, classguid, driver, configflags, mfg, friendlyname, location_information, physical_device_object_name, capabilities, ui_number, upperfilters, lowerfilters, bustypeguid, legacybustype, busnumber, enumerator_name, security, security_sds, devtype, exclusive, characteristics, address, ui_number_desc_format, device_power_data, removal_policy, removal_policy_hw_default, removal_policy_override, install_state, location_paths, or base_containerid. Refer to the documentation of SetupDiGetDeviceRegistryProperty in the Windows SDK for the meaning of these properties. Note that not all properties will exist for a device and the command will raise an error if an attempt is made to retrieve a non-existing property.

devinfoset_elements HDEVINFOSET

Returns a list containing the device elements within a device information set. HDEVINFOSET is a handle to a device information set as returned by devinfoset. Use device_element to extract each field in an element.

devinfoset_instance_ids HDEVINFOSET

Returns a list containing the device instance identifiers for all devices in a device information set. HDEVINFOSET is a handle to a device information set as returned by devinfoset.

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

rescan_devices

Asks the device manager to rescan the system for all devices.

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.

Device management

SYNOPSIS

DESCRIPTION

Media control

Device notifications

Physical disks

Device management

Commands

COPYRIGHT

TWAPI 4.5.2 Documentation