Tcl Windows API extension

The commands get_os_info and get_os_description allow retrieval of more detailed operating system information than the standard Tcl commands which do not distinguish between service packs, Professional versus Server versions and so on.

The command get_computer_name returns one of several forms of the system name. The command get_computer_netbios_name returns the NETBIOS name of the computer. Domain and workgroup information about the system can be obtained through the get_primary_domain_info command. find_domain_controller returns information about a domain controller with specified characteristics. get_primary_domain_controller returns the name of the primary domain controller of the computer.

The commands get_processor_count, get_processor_group_configuration and get_processor_info retrieve information about the processors in the system.

The command get_memory_info returns the physical and virtual memory configuration of the system.

The command get_system_time returns the current system time in high resolution. The command get_system_uptime returns the how long the system has been running. The command shutdown_system may be used to shutdown or reboot the system. The command abort_system_shutdown may be used to abort an ongoing system shutdown. The command suspend_system may be used to put the system in stand by or hibernate states. You can prevent the system from being suspended due to inactivity through the SetThreadExecutionState command. The commands logoff and lock_workstation may be used to log out of a user account and to lock a workstation respectively. Notifications regarding user switching, logon, logoff etc. can be enabled and disabled with the start_wts_session_monitor and stop_wts_session_monitor commands.

Various system settings related to the user experience can be retrieved and set through the get_system_parameters_info and set_system_parameters_info commands.

Commands

abort_system_shutdown ?-system SYSTEM?

Aborts a previously initiated system shut down or reboot. Note this is only possible if the system shutdown was initiated with a non-zero timeout value. The command enables any required privileges and restores the original privileges before returning.

find_domain_controller ?options?

Returns the name of a domain controller with specified characteristics and optionally, details about its characteristics and capabilities.

-allowstale BOOLEAN	If specified as true, the system will return cached domain controller information even if it is marked as expired. Default is false. This option has no effect if -rediscover is specified as true.
-avoidself BOOLEAN	If specified as true, and the command is run on a domain controller, the domain controller will return the name of another domain controller, not itself. Default is false.
-domain DOMAINNAME	Specifies the domain whose domain controller is to be retrieved. If unspecified, defaults to the primary domain of the computer.
-domainguid GUID	If the domain specified by the -domain option or the primary domain of system cannot be found, the command will attempt to return the domain controller for the domain with the specified GUID. Note this option may require -system to specify a system that knows about the specified domain GUID.
-getdetails	By default, the command returns the name of the domain controller. If this option is specified, the command returns detailed information whose format is described below.
-inputnameformat NAMEFORMAT	Specifies the format of the specified domain name. NAMEFORMAT may be one of dns, which implies DNS format, netbios which implies flat Netbios format, or any (default) which results in the command searching both namespaces.
-justldap BOOLEAN	If specified as true, the command searches for a LDAP server without caring if it is a domain controller.
-rediscover BOOLEAN	If specified as true, the system ignores any cached domain controller data. Default is false. Note specifying this option as true significantly increases the time to execute the command.
-outputaddrformat ADDRFORMAT	If ADDRFORMAT is specified as ip, the -dcaddr field in the returned information is the Internet address.
-outputnameformat NAMEFORMAT	Specifies the format in which the domain controller and domain names should be returned. NAMEFORMAT may be one of dns, which implies DNS format, netbios which implies flat Netbios format, or any (default). The command will raise an error if the name is not available in the specified format.
-prefer FEATURE	Indicates that the domain controller that support the specified features and services is returned in preference to one that does not. FEATURE is either directoryservice or timeserver (see below).
-require FEATURELIST	Indicates that the domain controller to be returned must support the specified features and services. FEATURELIST is a list of zero or more features from the following: directoryservice (Active Directory support), globalcatalog (global catalog server for the forest rooted by this domain), pdc (primary domain controller for this domain) kdc (Kerberos Key Distribution center service) timeserver (running Windows Time Service) writable (must not be read-only). Note that the features pdc, kdc and globalcatalog are mutually exclusive and must not be specified together.
-site SITENAME	Specifies the name of the site where the domain controller should be physically located. If an empty string (default), the command will attempt to return a controller in a site that is closest to the site of the system specified by the -system option.
-system COMPUTERNAME	Specifies the DNS or NETBIOS name of the computer on which the lookup is to be done. If unspecified, defaults to the local system.

If the -getdetails option is specified, the command returns detailed information about the controller instead of just its name. The returned information is a flat list of key value pairs with the following elements:

-clientsite	The name of the site containing the system specified by the -system option.
-dcname	Name of the domain controller which may be either in DNS or Netbios format.
-dcnameformat	Either dns if the -dcname field is in DNS format, or netbios if it is a Netbios name.
-dcaddr	Address of the domain controller. This may be either the Netbios address or the IP address depending on the value of the specified -outputaddrformat option.
-dcaddrformat	Either ip if the -dcaddr field is in IP address format, or netbios if it is a Netbios address.
-dcsite	The name of the site containing the domain controller.
-dnsforest	Name of the domain that is at the root of the directory service tree.
-dnsforestformat	Either dns if the -dnsforest field is in DNS format, or netbios if it is a Netbios name.
-domainguid	GUID of the domain.
-domain	Name of the domain.
-domainformat	Either dns if the -domain field is in DNS format, or netbios if it is a Netbios name.
-features	Contains a list describing domain controller features. This list may contain zero or more of the following: closest (domain controller is closest site to client), directoryservice (Active Directory support), ldap (supports LDAP access), globalcatalog (global catalog server for the forest rooted by this domain), pdc (primary domain controller for this domain), kdc (Kerberos Key Distribution center service), timeserver (running Windows Time Service), goodtimeserver (running Windows Time Service with a physical clock), writable (is not read-only).

Note that any of these fields may have empty string values if the information is not relevant or cannot be found.

get_computer_name ?NAMETYPE?

Returns the name of the computer. NAMETYPE must be one of the following:

netbios	Returns the NETBIOS name of the local computer or the cluster virtual server if it is in a cluster.
dnshostname	Returns the DNS host name of the local computer or the cluster virtual server if it is in a cluster.
dnsdomain	Returns the DNS domain of the local computer or the cluster virtual server if it is in a cluster.
dnsfullyqualified	Returns the fully qualified DNS domain of the local computer or the cluster virtual server if it is in a cluster.
physicalnetbios	Returns the NETBIOS name of the local computer.
physicaldnshostname	Returns the DNS host name of the local computer.
physicaldnsdomain	Returns the DNS domain of the local computer.
physicaldnsfullyqualified	Returns the fully qualified DNS name of the local computer.

If NAMETYPE is not specified, it defaults to netbios.

get_computer_netbios_name

Returns the NETBIOS name of the computer.

get_memory_info ?options?

Returns various information about the physical and virtual memory configuration of the system. The information returned is in the form of a flat list of the form "field1 value1 field2 value2 ..." depending on which of the following options are specified:

-all	Returns all the options listed below.
-allocationgranularity	Returns the granularity with which virtual memory is allocated.
-availcommit	Returns the amount of additional memory that can be committed by the system without extending the paging files.
-availphysical	Returns the amount of free physical memory.
-kernelpaged	Returns the amount of memory in the kernel paged pool.
-kernelnonpaged	Returns the amount of memory in the kernel non-paged pool.
-maxappaddr	Returns the highest address that may be mapped into an application's address space.
-minappaddr	Returns the lowest address that may be mapped into an application's address space.
-pagesize	Returns the size of a virtual memory page
-peakcommit	Returns the peak size of the paging files since the last system reboot.
-physicalmemoryload	Percentage of physical memory currently in use.
-processavailcommit	Returns the amount of additional memory that can be committed by the current process.
-processcommitlimit	Returns the maxiumm amount of memory that can be committed by the current process.
-processtotalvirtual	Size of the user-mode virtual address space of the current process.
-processavailvirtual	Size of the user-mode virtual address space that is currently not reserved or committed.
-systemcache	Returns amount of memory used for the system cache.
-swapfiles	Returns a list of the swap files for the system.
-swapfiledetail	Returns a flat list of pairs corresponding to the swap files. The first element of each pair is the name of the swap file. The second element is a list of consisting of the current size of the file (in pages), the number of pages in use, and the peak number of pages that have been used in the file.
-totalcommit	Returns the maximum amount of virtual memory that can be committed without extending the swap files.
-totalphysical	Returns the total amount of physical memory installed in the system.
-usedcommit	Returns the current size of memory committed.

get_numa_config

Returns the NUMA configuration of the system as a dictionary keyed by the NUMA node number. The corresponding value is a nested dictionary with keys -group and -processormask which processors in a processor group comprise that NUMA node.

Returns an empty string if the Windows version does not support NUMA.

get_primary_domain_controller ?options?

Returns the primary domain controller (PDC) for a domain. The command find_domain_controller should be preferred to this command.

The following options may be specified:

-domain DOMAINNAME	Specifies the domain whose PDC is to be retrieved. If unspecified, defaults to the primary domain.
-system COMPUTERNAME	Specifies the DNS or NETBIOS name of the computer on which the lookup is to be done. If unspecified, defaults to the local system.

get_primary_domain_info ?options?

Returns information about the primary domain or workgroup of the system as a flat list of option value pairs. The following options control what information is returned.

-all	Equivalent to specifying all options.
-dnsdomainname	Returns the DNS name of the primary domain.
-dnsforestname	Returns the DNS forest name of the primary domain.
-domainguid	Returns the GUID of the primary domain.
-name	Returns the domain or workgroup name.
-sid	Returns the SID of the primary domain.
-type	Returns workgroup or domain depending on whether the system belongs to a workgroup or a domain.

If the system belongs to a workgroup, all options will return empty values except -name and -type.

get_os_description

This commmand returns the same operating system information as returned by get_os_info but in a form suitable for displaying to a user.

get_os_info

This command retrieves operating system version and configuration information and returns a keyed list with the following fields:

os_build_number	Contains the operating system build number.
os_major_version	Major operating system version.
os_minor_version	Minor operating system version.
sp_major_version	Major service pack version.
sp_minor_version	Minor service pack version.
suites	Contains a list of values (see below) that indicate various options that may be installed as part of the operating system.
system_type	Indicates the operating system base type. This is workstation for Windows NT 4.0 Workstation, Windows 2000 Professional, or any Windows XP operating system versions. If the system is a domain controller, this value is domain_controller. In all other cases, this value is server.

The suites element in the returned array contains a list of values from the following set that indicates additional operating system components that are present:

backoffice	Microsoft BackOffice components are installed.
blade	Windows .NET Server 2003 family Web Edition is installed.
communications	A version of Microsoft Office Communications Server is installed.
compute_server	Windows Server 2003 family Computer Cluster Edition is installed.
datacenter	Datacenter version of Windows 2000, Windows Server 2003 or Windows Server 2008 is installed.
embeddednt	Windows XP Embedded is installed.
embedded_restricted
enterprise	Windows 2000 Advanced Server, or the Enterprise version of Windows Server 2003 or Windows Server 2008 is installed.
personal	A Home Edition of Windows XP, Windows Vista or Windows 7 is installed.
security_appliance	A hardened installation of Windows Server 2003 in a security appliance.
singleuserrts	Remote desktop is supported only for a single interactive session.
smallbusiness	Microsoft Small Business Server is installed.
smallbusiness_restricted	Microsoft Small Business Server is installed with the restrictive client license in force.
storage_server	A Windows Storage Server version of Windows 2003 or Windows 2003 R2 is installed.
terminal	Terminal Services are installed.
wh_server	Windows Home Server is installed.

get_os_version

This command returns the operating system version as list of four elements - the operating system major version number, the operating system minor version number, the service pack major version number, the service pack minor version number.

get_processor_count

Returns the number of processors in the system.

get_processor_group_config

Newer versions of Windows partition processors into processor groups when there more than 64 processors in the system. This command returns information about how the groups are configured. The return value is a dictionary with two keys, -maxgroupcount which is the maximum number of processor groups that can be configured in the system, and -activegroups which is a dictionary keyed by the processor group number. The corresponding value is a nested dictionary with keys -maxprocessorcount, -activeprocessorcount and -processormask which contains the maximum number of processors that can be configured in the group, the number of currently active processors and the group's processor mask.

On older versions of Windows, the information returned will contain the single processor group 0.

get_processor_info PROCESSOR ?options?

Returns various pieces of information related to the processors in the system. PROCESSOR identifies the processor whose information is to be retrieved. If specified as an empty string, information across all processors in the processor group for the current process is returned. Note this is different from processors across the entire system when it has more than 64 processors.

The return value is a dictionary keyed by the specified options:

-all	Returns all fields listed below.
-arch	Returns the processor architecture.
-dpctime	The amount of CPU time in 100ns units spent in servicing deferred procedure calls. Note this value is included in the -privilegedtime value.
-idletime	The amount of idle CPU time in 100ns units since system start. Note this value is included in the -privilegedtime value.
-interrupts	Returns the total number of interrupts serviced since system start.
-interrupttime	The amount of CPU time in 100ns units spent in servicing interrupts. Note this value is included in the -privilegedtime value.
-privilegedtime	The amount of privileged (kernel) context CPU time since system start in 100ns units. Note this includes the DPC, interrupt and idle CPU cycles.
-processormodel	Returns the processor model. PROCESSOR must not be an empty string if this option is specified.
-processorname	Returns a human readable form of the processor description. PROCESSOR must not be an empty string if this option is specified.
-processorrev	Returns the processor revision as defined by the CPU manufacturer. PROCESSOR must not be an empty string if this option is specified.
-processorspeed	Returns the nominal speed in Mhz of the processor PROCESSOR must not be an empty string if this option is specified.
-processorlevel	Returns the processor level as defined by the CPU manufacturer.
-usertime	The amount of user context CPU time in 100ns units since the system was started.

get_system_parameters_info PARAMETER

This command wraps the Windows SystemParametersInfo function and allows retrieval of various user interface settings such as screensaver timeout, mouse speed etc. The information retrieved depends on the PARAMETER which must be one of the SPI_ symbols listed in the SystemParametersInfo documentation.

get_system_sid

Returns the SID of the system.

get_system_time

Returns the current system time in UTC as the number of 100 nanosecond units since Jan 1, 1601. This can be converted to a format suitable for use with the clock command through the use of the command large_system_time_to_secs_since_1970.

get_system_uptime

Returns the number of seconds elapsed since the system was booted.

lock_workstation

Initiates a request to lock the work station display.

logoff ?-force? ?-forceifhung?

Logs off the current session. If -force is specified, it forces processes to terminate without notifying them. This options should generally not be specified as it can result in data loss. If -forceifhung is specified, it only terminates processes if they do not respond to the session end notifications.

min_os_version osmajor ?osminor? ?spmajor? ?spminor?

This function checks that the operating system version meets the specified minimum version. It returns 1 if the operating system version is greater than osmajor.osminor.spmajor.spminor. Otherwise it returns 0. Any unspecified optional arguments default to 0.

set_system_parameters_info PARAMETER VALUE ?-persist? ?-notify?

This command wraps the Windows SystemParametersInfo function and allows setting of various user interface settings such as screensaver timeout, mouse speed etc. The information retrieved depends on the PARAMETER which must be one of the SPI_ symbols listed in the SystemParametersInfo documentation. The corresponding setting is assigned VALUE.

If the -persist is specified, the changed setting is written to the user's profile. If -notify is specified, all applications are notified of the change. Note -notify only has effect if -persist is also specified since other applications will update based on the user's persistent profile.

shutdown_system ?options?

Initiates a system shut down or reboot. The command enables any required privileges and restores the original privileges before returning.

The following options may be specified:

-system SYSTEMNAME	Specifies the system to be shut down. By default, this is the local system.
-timeout SECONDS	Specifies the amount of time to wait before shutting down the system. During this time, a shutdown dialog is displayed to the user. If a value of 0 is specified, the system is shut down immediately and no dialog is displayed to the user.
-message MESSAGE	Specifies a message to be displayed to the user in the shutdown dialog.
-force	Normally, the system displays a dialog box asking the user to close any applications with unsaved data. If the -force option is specified, applications are forcible closed resulting in possible data loss.
-restart	If specified, the system is restarted after the shut down.

start_wts_session_monitor COMMAND ?-all?

Starts monitoring state of Windows Terminal services sessions. Any changes will result in the command prefix COMMAND being invoked with two additional arguments - the numeric value identifying the change and the session identifier of the session whose state changed. See the SDK documentation of the WM_WTSSESSION_CHANGE Windows message for possible event change values.

By default, only events for the current session are monitored. Specify the -all option to monitor events for all sessions.

The command returns a handle that must be passed to stop_wts_session_monitor to stop the monitor when no longer required.

stop_wts_session_monitor WTS_MONITOR_ID

Stops monitoring of Windows Terminal services sessions. WTS_MONITOR_ID must be a handle returned by a previous call to start_wts_session_monitor.

suspend_system ?options?

Places the system in a stand by or hibernate state. The command takes the following options:

-state STATE	STATE must be one of standby (default) or hibernate depending on whether the state into which the system is to be placed.
-force BOOLEAN	If false (default), the system sends a PBT_ATMQUERYSUSPEND message to all applications before placing the system in stand by or hibernate states. If this option is specified as true, the message is not sent and the system is immediately placed into the appropriate state.
-disablewakeevents BOOLEAN	If false (default), system wake events remain enabled. If true they are disabled.

System

SYNOPSIS

DESCRIPTION

Overview

Commands

COPYRIGHT

TWAPI 4.7.1 Documentation