Tcl Windows API extension

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.

Volumes

The command find_volumes returns a list of volumes on the system. The command get_volume_info returns various information about a volume (logical drive) including size and space utilization, file system characteristics and device.

The command find_volume_mount_points returns the list of volume mount points on a particular volume. Commands mount_volume and unmount_volume can be used to set and remove volumes from volume mount points. The command get_mounted_volume_name will return the name of the volume mounted on a drive letter or volume mount point.

The command volume_properties_dialog displays the shell property sheet dialog for a volume.

Logical drives

For all drive related commands, the drive parameter may be specified as a single drive letter, a drive letter followed by a :, or as the root path of the drive (eg. C:\)

The command find_logical_drives returns a list of drives in the system of a specified type. get_drive_type returns the type (fixed, remote, etc.) of the logical drive.

The command user_drive_space_available can be used to check if sufficient free space is available on a drive.

The command set_drive_label may be used to set the volume name (drive label).

The command map_drive_local and unmap_drive_local may be used to assign and unassign a drive letter to a local path.

File system

The commands begin_filesystem_monitor and cancel_filesystem_monitor can be used for monitoring changes to the file system.

The get_file_version_resource returns various information stored within the version resource of a file.

The command file_properties_dialog displays the shell property sheet dialog for a file.

The commands get_file_times and set_file_times and allow retrieval and setting of the times associated with a file.

Commands

begin_filesystem_monitor PATH SCRIPT ?options?

Registers SCRIPT to be invoked when the specified types of changes occur in the directory of subtree matching PATH.

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 cancel_filesystem_monitor to end the monitoring.

The following options specify the type of changes to be monitored:

-access BOOLEAN	If true, changes to the last access time are monitored.
-attr BOOLEAN	If true, attribute changes, are monitored.
-create BOOLEAN	If true, changes to the creation times are monitored.
-dirname BOOLEAN	If true, directory name changes, including creation and renaming, are monitored.
-filename BOOLEAN	If true, file name changes, including file creation, renaming and deletion, are monitored.
-patterns PATTERNLIST	If specified, notification callbacks are invoked only on those files and directories that match one of the patterns in PATTERNLIST. See below for more detail.
-secd BOOLEAN	If true, changes to security descriptors in the specified directories are monitored.
-size BOOLEAN	If true, size changes in the specified directories are monitored.
-subtree BOOLEAN	If true, all subdirectories under the specified directory PATH are monitored in addition to PATH itself. If false (default), only the directory indicated by PATH is monitored.
-write BOOLEAN	If true, changes to the last write time of files in the specified directories are monitored.

By default, all options are false if unspecified. However, if no options related to the type changes to be monitored are present (either true or false), the command will monitor all types of changes.

When a file system change is detected, the SCRIPT is invoked after being appended with a list each element of which is a pair consisting the notification type and the file or directory name (except when the type is error). The type is one of the following values:

added	The file or directory was added.
removed	The file or directory was deleted.
modified	The file or directory was modified. This includes changes to attributes or timestamps.
renameold	The file or directory was renamed. The associated name is the old name.
renamenew	The file or directory was renamed. The associated name is the new name.
error	There was an error in the operation. In this case the second element is the identifier of the callback for which the error occurred and the third element an error message. On receiving an error notification, the monitoring should generally be canceled by calling cancel_filesystem_monitor.

Note that the file names being reported may be either in longname or shortname (8.3) format. Moreover, depending on the buffering and caching by the operating system, a single write may result in one or more notifications.

If the -patterns option is specified, then the value associated with the option is a pattern filter that is used to match against the name component being reported. SCRIPT will be invoked only if the pattern filter matches.

Each element of the pattern list is a string beginning with either + or - followed by a pattern that is used for matching using the same rules as for the Tcl string match -nocase command. Note that \ path separator need to be escaped with another \ just as in the string match case. Alternatively, you can use / as the path separator in the pattern.

The name component being reported is matched against each element of the pattern list. When a match occurs, further elements of the pattern list are not matched. If the matching element is prefixed with a +, then SCRIPT is invoked. If the matching element is prefixed with a -, then the pattern filter is deemed to have not matched and SCRIPT is not invoked for the notification. Even in this case, no further matching is attempted against the remaining patterns. Pattern elements that do not begin with +, or - are treated as having an implicit + prefix.

If a non-empty pattern filter is specified but no element matches, the pattern filter is treated as having not matched, and SCRIPT is not invoked. Thus a pattern filter that only has - type elements will never match anything. Note a pattern list where no element matches is different from the case where -patterns is not specified or PATTERNLIST is empty in which case the pattern filter is treated as matched.

Note that the pattern matching is done only against the name component being reported, not against the full path.

Some examples of pattern matching are below (assume callback is your SCRIPT procedure):

begin_filesystem_monitor c:/temp callback -patterns {*.exe}

will only monitor files in c:\temp with .exe extensions.

begin_filesystem_monitor c:/temp callback -patterns {-*.foo +*.fo*}

will monitor files in c:\temp with an extension beginning with .fo except if the extension is .foo.

begin_filesystem_monitor c:/temp callback -patterns {+*.fo -*.foo}

will monitor files in c:\temp with an extension beginning with .fo including those with extension .foo. The second pattern -*.foo has no effect as the matching stops as soon as a match is found.

cancel_filesystem_monitor MONITORID

Cancels monitoring of the file system corresponding to MONITORID which must be an identifier returned by begin_filesystem_monitor.

find_logical_drives ?-type DRIVETYPELIST?

Returns a list of the logical drives in the system. If option -type not specified, all drives in the system are returned. Otherwise, only drives whose type is in DRIVETYPELIST are returned. DRIVETYPELIST must be a subset of the values returned by the get_drive_type command.

Example: List all drives on a system

Example: List the remote drives on a system

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.

file_properties_dialog FILEPATH ?options?

Displays the shell property dialog for the specified file. The following options may be specified:

-hwin HWIN	If specified, HWIN is the handle to the window to be used as the parent for the dialog.
-page PAGENAME	Specifies the name of the property sheet page to be displayed. If unspecified, the default page is displayed.

find_volumes

Returns the list of volumes in the system. Each entry in the list includes a trailing slash.

find_volume_mount_points VOLNAME

Returns the list of volume mount points on the volume whose name is VOLNAME.

get_drive_info DRIVE ?options?

Synonym for get_volume_info.

get_drive_type DRIVE

Returns the type of the drive - unknown, removable, fixed, remote, cdrom or ramdisk or invalid.

get_file_times FILE ?options?

Retrieves the creation, access and modification timestamps for a file. The latter two are available through the Tcl file command which however does not provide the creation time for a file. FILE may either be the path to the file, an open Tcl channel to the open file or a Win32 handle to an open file. In the latter two cases, the file must have been opened for read access.

The information returned is a flat list of option value pairs. options, which may contain one or more of the following values, controls the information returned.

-all	Returns all fields.
-atime	Returns the time of last access for the file.
-ctime	Returns the creation time for the file.
-mtime	Returns the time of last modification for the file.

All times are returned in the same format as get_system_time.

get_file_version_resource PATH ?options? ?STRINGNAME...?

Returns the information stored within the version resource of a file. The command will generate a Tcl error if the file specified by PATH does not contain a version resource.

The version resource consists of two parts. The information in the first part is in a fixed format and can be retrieved by specifying appropriate options in options. The second part is a string table, the entries in which can be retrieved by specifying the key as a STRINGNAME argument.

The following options may be used with the command:

-all	Returns all information in the fixed part.
-datetime	Returns the date and time the file was created (as stored in the version resource) as a 64 bit number. Refer to large_system_time_to_timelist or large_system_time_to_secs_since_1970.
-fileversion	Returns the file version as indicated in the version resource. This is returned in the format MAJOR.MINOR.BUILD.PRIVATE. Note this is not necessarily identical to the value specified for the FileVersion entry in the string table.
-fileos	Returns a value specifying the platform for which the file was designed. This may be one of dos (MS-DOS), os216 (16-bit OS/2), os232 (16-bit OS/2), nt (Windows NT), wince (Windows CE), windows16 (16-bit Windows), pm16 (16-bit Presentation Manager), pm32 (32-bit Presentation Manager), windows32 (32-bit Windows), dos_windows32 (32-bit Windows on MS-DOS), os216_pm16 (16-bit Presentation Manager on 16-bit OS/2), os232_pm32 (32-bit Presentation Manager on 32-bit OS/2) or nt_windows32 (32-bit Windows on Windows NT).
-filetype	Returns the file type which may be one of the following: application, dll, driver.printer, driver.keyboard, driver.language, driver.display, driver.mouse, driver.network, driver.system, driver.installable, driver.sound, driver.comm, driver.inputmethod, driver.versionedprinter, driver.DRIVERSUBTYPENUMBER, font.raster, font.vector, font.truetype, font.FONTSUBTYPENUMBER, vxd.VIRTUALDEVICEID, staticlib or FILETYPENUMBER.FILESUBTYPENUMBER. (Note in cases where the file type or subtype is not recognized, the actual numeric value is returned.)
-flags	Returns a list of symbols corresponding to flags set in the version resource. The list may contain symbols from the following: debug, prerelease, patched, privatebuild, infoinferred and specialbuild. In addition, the list may also contain a numeric value corresponding to bits that are set but are not recognized as one of the above.
-foundcodepage	Returns the code page of the matched string table (see below).
-foundlangid	Returns the language of the matched string table (see below). The returned value is a list of two elements containing the numeric language identifier and a description string for the corresponding language.
-langid LANGID	Specifies LANGID as the language identifier to be used for string table lookup (see below). By default, the language identifier returned by get_user_ui_langid is used.
-codepage CODEPAGE	Specifies CODEPAGE as the code page to be used for string table lookup (see below).
-productversion	Returns the product version as indicated in the version resource. This is returned in the format MAJOR.MINOR.BUILD.PRIVATE. Note this is not necessarily identical to the value specified for the ProductVersion entry in the string table.
-signature	Contains a longword that is a signature for the fixed part of the version resource. Not particularly useful for the application.
-structversion	Returns the version of the version resource format.

In addition to the options that retrieve fixed portions of the version resource, the caller may also specify string names corresponding to language-specific string tables in the version resource. Each such STRINGNAME is looked up in the string table and returned as a STRINGNAME VALUE pair. If a particular string name does not exist in the string table, an empty string is returned as its value. The following string names are commonly defined in version resources: Comments, InternalName, ProductName, CompanyName, LegalCopyright, ProductVersion, FileDescription, LegalTrademarks, PrivateBuild, FileVersion, OriginalFilename, SpecialBuild.

The version resource may contain multiple string tables for different languages and code pages. The caller can control the string table used through the -langid and -codepage options. The command uses the following algorithm in selecting the string table that is looked up.

If a string table exactly matches the language id and code page, it is used.
Otherwise, if a string table exactly matches the language id, it is used irrespective of the code page.
Otherwise, a string table matching the primary language portion of the language id and the code page is used.
Otherwise, a string table matching the primary language portion of the language id is used regardless of the code page.
Otherwise, a string table specified as language neutral is used.
Otherwise, a string table specified as English is used.
Finally, the string table corresponding to the first language and code page specified in the resource is used.

The language identifier and code page corresponding to the actual string table that was looked up may be optionally be retrieved by passing the -foundlangid and -foundcodepage to the command.

get_mounted_volume_name MOUNTPOINT

Returns the name of a mounted volume. The returned name has a trailing backslash appended. MOUNTPOINT must specify a root directory of a local drive or path to a volume mount point. Specifying remote file shares will generate an error.

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. The value of the -partitionstyle field is one of the values mbr, gpt, raw or unknown. 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.

get_volume_info DRIVE ?options?

Returns attributes and properties of the specified volume as a list of the form "option1 value1 ...". DRIVE may be either a DOS drive, file share or a volume. Note certain options are not valid except when DRIVE specifies a drive letter (see below).

The values returned depend on which of the following options are specified:

-all	Returns all fields except -type and -device which have to be explicitly specified since they are not valid for volumes.
-attr	Returns a list containing one or more of the values case_preserved_names, unicode_on_disk, persistent_acls, file_compression, volume_quotas, supports_sparse_files, supports_reparse_points, supports_remote_storage, volume_is_compressed, supports_object_ids, supports_encryption, named_streams, or read_only_volume. These indicate the features supported by the drive's file system. Refer to the documentation for GetVolumeInformation function in the Windows SDK for details on these.
-device	Returns a list the first element of which is the device name mapping for the drive. Remaining elements containing prior undeleted mappings for the drive. Only valid if DRIVE is a drive letter. For UNC paths, an empty string will be returned.
-extents	Returns a list of disk extents describing the physical location of the volume. Each disk extent is a keyed list containing 3 fields: -disknumber identifying the physical disk, -startingoffset containing the byte offset in the physical disk that the extent starts at, and -extentlength containing the size of the extent. An empty list is returned for extents if they cannot be determined (for example, for remote drives).
-freespace	Returns the total size of the unused space on the drive in bytes.
-fstype	Returns the type of the file system on the volume (eg. NTFS).
-label	Returns the label of the drive.
-maxcomponentlen	Returns the maximum length allowed for a single component in a file path.
-serialnum	Returns the serial number of the drive in hexadecimal format.
-size	Returns the size of the drive in bytes.
-type	Returns the type of the drive. Only valid if DRIVE is a drive letter. This may have one of the values unknown, removable, fixed, remote, cdrom or ramdisk. In case the drive path is invalid, the value invalid is returned in this field.
-used	Returns the total size of the used space on the drive in bytes.
-useravail	Returns the total size of the unused space on the drive that is available for the caller. This may be less than the freespace field if quotas are in effect.

Example: List drives that are almost full

Example: Check if the given drive supports unicode filenames

get_volume_mount_point_for_path PATH

Returns the volume mount point below which the file specified by PATH resides. Refer to documentation for GetVolumePathName in the Windows SDK for more details.

map_drive_local DRIVE PATH ?options?

Maps the fully qualified path PATH to the specified drive letter. The mapping established by this command is not persistent across reboots. It may also be removed using the unmap_drive_local command.

The following options may be specified with the command:

-raw

Specifies that PATH is a raw path specification that includes the device name as opposed to a drive letter.

mount_volume MOUNTPOINTPATH VOLNAME

Mounts the volume specified by VOLNAME at the mount point specified by MOUNTPOINTPATH. The directory MOUNTPOINTPATH must be empty. VOLNAME must be of the form \\?\VOLUME{GUID}\. If any volume is already mounted at MOUNTPOINTPATH, it will be silently unmounted before the new mount is performed.

set_drive_label DRIVE NAME

Sets the volume name for the specified drive. NAME may be an empty string in which case the drive label is removed.

Example: Change the label of a drive

set_file_times FILE ?options?

Sets the creation, access or modification timestamps for a file. FILE may either be the path to the file, an open Tcl channel to the open file or a Win32 handle to an open file. In the latter two cases, the file must have been opened for write access.

The timestamps modified depend on the options specified:

-atime LARGETIMESTAMP	Sets the time of last access for the file.
-ctime LARGETIMESTAMP	Sets the creation time for the file.
-mtime LARGETIMESTAMP	Sets the time of last modification for the file.
-preserveatime	Indicates that the time of last access for an open file should be preserved and not updated when the file is closed. This option can only be specified if FILE is either an open Tcl channel or Win32 handle and not if it is a file path. Also, the option cannot be used together with -atime.

All time values must be specified in the same format as get_system_time. You can use secs_since_1970_to_large_system_time to convert the format used by Tcl's clock command to this format.

unmap_drive_local DRIVE ?options?

Unmaps the drive specified by DRIVE. This must reference a local drive. The following options may be specified with the command:

-path PATH	Specifies that the drive should be unmapped only if it refers to the location specified by PATH. This is useful to ensure drive letters are not unmapped when they have been redefined to point elsewhere.
-raw	Specifies that PATH argument specified with the -path option is a raw path specification that includes the device name as opposed to a drive letter.

unmount_volume MOUNTPOINTPATH

Unmounts the volume at the mount point specified by MOUNTPOINTPATH. If MOUNTPOINTPATH is a root directory of a drive, the corresponding DOS drive letter mapping is removed.

user_drive_space_available drive space

Returns 1 if the given drive has at least space bytes free, and 0 otherwise. Note that space is compared to the free bytes available to the caller as opposed to total free bytes on the drive. The former may be smaller if disk quotas are being enforced on the drive.

Example: Check available disk space

volume_properties_dialog VOLUME ?options?

Displays the shell property dialog for the specified volume. The following options may be specified:

-hwin HWIN	If specified, HWIN is the handle to the window to be used as the parent for the dialog.
-page PAGENAME	Specifies the name of the property sheet page to be displayed. If unspecified, the default page is displayed.

Files, Disks and Volumes

SYNOPSIS

DESCRIPTION

Physical disks

Volumes

Logical drives

File system

Commands

COPYRIGHT

TWAPI 2.2.3 Documentation