Base module

Base module used by all TWAPI components

SYNOPSIS

package require twapi_base
cancel_wait_on_handle HANDLE
canonicalize_guid GUID
close_handle HANDLE
conceal PLAINTEXT
confirm_credentials TARGET VALIDITY
create_file PATH ?options?
cred_confirm TARGET VALIDITY
cred_prompt_console TARGET ?options?
cred_prompt_gui TARGET ?options?
debuglog ?MESSAGE?
debuglog_clear
debuglog_disable
debuglog_enable
debuglog_get
duplicate_handle HANDLE ?options?
export_public_commands
format_message ?options?
free_library HMODULE
get_build_config ?CONFIGKEY?
get_handle_inheritance HANDLE
get_tcl_channel_handle CHANNEL DIRECTION
get_version ?-patchlevel?
hex BIN
hex32 INT32VAL
hex64 INT64VAL
import_commands
is_valid_sid_syntax sid
lambda ARGLIST BODY ?NAMESPACE?
large_system_time_to_secs_since_1970 SYSTEMTIMEVALUE ?BOOLEAN?
large_system_time_to_timelist SYSTEMTIMEVALUE
load_library FILEPATH ?options?
lookup_account_name name ?options?
lookup_account_sid sid ?options?
make_logon_identity USERNAME PASSWORD DOMAIN
map_account_to_name ACCOUNT ?-system SYSTEMNAME?
map_account_to_sid ACCOUNT ?-system SYSTEMNAME?
map_windows_error ERRORCODE
new_uuid ?-localok?
nil_uuid
new_guid
parseargs ARGLISTVAR OPTLIST ?-ignoreunknown? ?-nulldefault? ?-hyphenated? ?-maxleftover MAXLEFTOVER? ?-setvars?
random_bytes NUMBER
read_credentials ?options?
recordarray cell RECORDARRAY INDEX FIELD
recordarray column RECORDARRAY FIELD ?-filter FILTERLIST?
recordarray concat ?RECORDARRAY RECORDARRAY...?
recordarray fields RECORDARRAY
recordarray get RECORDARRAY ?options?
recordarray getdict RECORDARRAY ?options?
recordarray getlist RECORDARRAY ?options?
recordarray index RECORDARRAY INDEX ?options?
recordarray iterate ARRAYVAR RECORDARRAY ?options? BODY
recordarray range RECORDARRAY LOW HIGH
recordarray rename RECORDARRAY FIELDRENAMEMAP
recordarray size RECORDARRAY
rethrow
reveal ENCRYPTED
safearray TYPE LISTVALUE
secs_since_1970_to_large_system_time SECONDS
set_handle_inheritance HANDLE BOOLEAN
swap2 BYTES2
swap4 BYTES4
swap8 BYTES8
timelist_to_large_system_time TIMELIST
tclcast TYPE VALUE
tcltype VALUE
trap SCRIPT ?onerror ERRORPATTERN ERRORSCRIPT?... ?finally FINALSCRIPT?
wait_on_handle HANDLE ?options?
win32_error WINERROR ?MESSAGE?

DESCRIPTION

This module implements core commands required by all other TWAPI components and some functionality commonly required in all Windows application.

Package information

get_version returns TWAPI version information. export_public_commands and import_commands enable export and import of commands defined in the TWAPI namespace.

Handles

Several Win32 and TWAPI commands return operating system handles to various types of resources. The following commands allow manipulation and retrieval of information regarding handles.

The command create_file returns a handle to a file or device.

The operating system associated with a Tcl channel can be retrieved using the get_tcl_channel_handle command.

The command duplicate_handle can be used to duplicate a handle, for example to pass down to a child process with different access rights.

The command close_handle closes a operating system handle and frees resources associated with it.

An application can wait on a handle to be signalled using the wait_on_handle command. The wait can be cancelled by calling cancel_wait_on_handle command.

User Accounts

The twapi_base package includes some commonly used commands related to user accounts. The command lookup_account_name, map_account_to_name, lookup_account_sid and map_account_to_sid translate between user and group account names and their SID's. The command is_valid_sid_syntax validates the syntax of an SID.

A more complete set of commands related to accounts, credentials and security are in the twapi_account and twapi_security packages.

Passwords

Commands cred_prompt_console, cred_prompt_gui, cred_get, and cred_confirm allow interfacing to the Windows credentials manager and getting user credentials such as passwords from the user.

make_logon_identity constructs a logon account, domain and password in a form required by many other commands.

Protecting data in memory

Passwords are sensitive data and need to be protected in memory. For example, in case of error exceptions being logged to file, plaintext passwords should not be exposed. The above commands return passwords in an encrypted form. TWAPI commands that deal with passwords expect them to be passed in this encrypted form. The conceal and reveal commands can also be used for this purpose. Note however using conceal is not as secure as the argument passed to it is still in clear text.

Writing to the Windows event log

Commands for writing to the Windows event log are included in the twapi_base package. Documentation for these is however part of the twapi_eventlog package.

Error generation and handling

The twapi_base module also provides various facilities for generating and handing errors and Tcl exceptions.

TWAPI generates Tcl exceptions when errors are encountered. Information pertaining to the error is stored in Tcl global variables as with any standard Tcl errors. The global variable errorInfo contains a traceback of the Tcl stack when the error occured. The global errorCode contains a list with additional information about the error. The first element is the error class and determines the format of the rest of the list. This may take one of the following values:

TWAPI_WIN32 This error class corresponds to Windows error codes. The second element of the list is the integer Windows error code. The map_windows_error can be used to retrieve the correesponding text description. The third element is the corresponding localized text string describing the error. The fourth element is optional and its format is dependent on the specific error code.

The command win32_error can be used to generate an error in this format.
TWAPI This error class is used for non-Windows related errors, for example invalid options to commands. The format is similar to that of TWAPI_WIN32 except that the error code is an internal TWAPI error code and the text is not localized.

For handling errors, the command trap provides exception handling with finalization features.

For troubleshooting and debug purposes, TWAPI provides the debuglog command which writes to an internal log. This command is normally a no-op and must be enabled with debuglog_enable for logging to have effect. It can be disabled again with debuglog_disable. The current contents of the debug log can be retrieved with debuglog_get.

Record arrays

Some TWAPI commands return data in a form that is similar to a table with named columns. For example, the event tracing module returns a list of event trace records. The form of the returned data is called a record array and is intended to be opaque and manipulated through the recordarray command. The command takes various forms shown in the table below and is flexible enough to retrieve data as dictionaries or lists as well as support operations like filtering and column slicing.

recordarray cell Returns the value in a specified field in a specific record.
recordarray column Returns values for a specified field for all records.
recordarray concat Returns a record array containing records from one or more record arrays.
recordarray fields Returns field names for the records in the record array.
recordarray get Returns another record array containing a subset of the records and fields.
recordarray getdict Returns a dictionary containing a subset of the records and fields.
recordarray getlist Returns a list containing a subset of the records and fields.
recordarray index Returns the record at a specified position in list or dictionary format.
recordarray iterate Iterates over the records in the record array.
recordarray range Returns a new record array containing records in the specified range.
recordarray rename Renames one or more fields in the record array.
recordarray size Returns the number of records in the record array.

Many record array commands accept some of the following common options:

-filter FILTERLIST Specifies a list of matching filters. Only the records matching all the filter expressions in FILTERLIST are returned. FILTERLIST is a list of filter expressions. Each filter expression is a 3 or 4 element list consisting of a record field name, a matching operator, the value to match and optionally a fourth element -nocase which may be used with any of the string or pattern matching operators to indicate that character case should be ignored. The matching operator must be one of the following:
eq String equality
ne Strings inequality
~ Pattern matched (as in string match)
!~ Pattern not matched (as in string match)
== Integer equality
!= Integer inequality
< Integer less than
<= Integer less than or equal
> Integer greater than
> Integer greater than or equal
-format FORMAT Specifies the format of each record element returned. FORMAT may be one of the following values:
list each record is returned as a list (default).
dict each record is returned as a dictionary whose keys are the fields names of the record array.
flat Field values of returned as a flat list. Only valid for the recordarray getlist command.
-slice FIELDLIST Specifies that the return value should only include the fields specified in FIELDLIST and in that order.

Here is an example that returns a plain list of PID of processes that have a privileged port (any port under 1024) open. get_tcp_connections returns a record array.

recordarray getlist [get_tcp_connections] -filter {{-localport < 1024}} -slice -pid -format flat

Another example, which shows all services that are marked as interacting with the desktop, returned as a dictionary keyed by the service name.

recordarray getdict [get_multiple_service_status] -filter {{interactive == 1}} -key name

Utility commands

parseargs

parses an argument list based on specified options. format_message formats a operating system or application message.

Commands large_system_time_to_secs_since_1970, large_system_time_to_timelist, secs_since_1970_to_large_system_time and timelist_to_large_system_time convert between various time formats.

A Universally Unique Identifier (UUID) can be generated by the command new_uuid. A nil UUID can be generated by nil_uuid. Similarly, a Globally Unique Identifier (GUID) which has a slightly different format can be generated by new_guid. In most commands, UUID's and GUID's are interchangeable. The command canonicalize_guid will convert a GUID into a canonical format that can be used for comparison.

The commands load_library and free_library can be used to load and free DLL's.

The commands tclcast and tcltype are useful for manipulating internal Tcl value types. This is sometimes useful and required when dealing with external APIs and data formats like COM. hex formats a binary string as a hexadecimal string. hex32 and hex64 format numbers as fixed length hexadecimal strings. lambda returns an anonymous proc definition based on the Tcl apply command.

Commands

cancel_wait_on_handle HANDLE
Cancels any previously registered asynchronous wait on a handle that was registered using wait_on_handle.
canonicalize_guid GUID
Returns the canonicalized form of GUID with hexadecimal letters converted to upper case and braces added.
close_handle HANDLE
Closes the operating system handle HANDLE. If the handle has been registered for asynchronous notifications via wait_on_handle, the notifications are canceled (via cancel_wait_on_handle).
conceal PLAINTEXT
Returns an encrypted binary string corresponding to PLAINTEXT. reveal can be used to decrypt the result within the same process. The returned value should never be used for comparisons as the same PLAINTEXT may result in different encrypted values on each call.
confirm_credentials TARGET VALIDITY
Deprecated. Use cred_confirm.
create_file PATH ?options?
This is a thin wrapper around the Win32 CreateFile function that returns a handle to a file or device. The wrapper primarily provides mnemonics and defaults for the CreateFile parameters. PATH specifies the file or device path. Additional options and default values are shown below.
-access ACCESSRIGHTS Specifies the desired access rights and may be specified as a list of integer access rights flags or symbols as described in Access Rights. Defaults to generic_read.
-createdisposition DISPOSITION DISPOSITION must be one of create_always, create_new, open_always, open_existing or truncate_existing. Refer to the Windows SDK for the meaning. Defaults to open_always.
-flags FLAGS An integer bit mask corresponding to the dwFlagsAndAttributes parameter to CreateFile function. See the Windows SDK for detail. Defaults to 0.
-inherit BOOL If true, the returned handle is inheritable by child processes. Defaults to false.
-secd SECURITY_DESCRIPTOR Specifies a security descriptor to be attached to the file or device if it has to be created. Defaults to a null security descriptor which results in the process' default security descriptor being applied.
-share Specifies the sharing mode of the object. This is list containing zero or more of the constants read, write and delete that control what kind of shared access should be allowed while the file or device is open. Defaults to {read write delete}.
-templatefile A handle to a template file with the GENERIC_READ access right from which file attributes and extended attributes are to be copied for the file that is being created. Defaults to NULL.
Refer to the Windows SDK for additional details.
cred_confirm TARGET VALIDITY
Informs the Windows Credentials Manager that the previously obtained credentials for the specified TARGET are valid or not. This command should be called whenever the user is prompted for credentials via cred_prompt_console or cred_prompt_gui with the -persist option specified as true. After the returned credentials are validated, the application should call cred_confirm with VALIDITY set to true. Conversely, if the credentials are invalid, cred_confirm should be called with VALIDITY set to false.
cred_prompt_console TARGET ?options?
Prompts the user for credentials via the console. TARGET is name of the target for the credentials, for example the server name. This is used as the key when retrieving credentials. The command returns a list of three elements, the user name, the password, and a boolean indicating whether the user selected for the credentials to be saved or not.

The following options may be specified:
-forceui BOOLEAN If specified as true, the user is prompted even if the credentials manager already has the requested credentials. Default is false. This option may only be used for generic credentials.
-persist BOOLEAN If true, credentials are to be persisted by the credentials manager if so desired by the user. Default is false. If specified as true, cred_confirm must be called with the result of the validation.
-showsaveoption BOOLEAN Specifies whether the user should be given the option to save the credentials. Defaults to false (meaning user is not shown the choice). Note if specified as true but the options -persist is not specified or is false, it is up to the caller to save credentials appropriately by some application-specific means.
-type TYPE Specifies the type of credentials. TYPE must be generic (default), domain or runas. If domain, if the entered user name is not fully qualified, it is returned qualified with TARGET as the domain. For generic, user names are returned as entered. If runas, the -username option must be specified and if unqualified, is qualified with the name of the system in the returned list.
-username USERNAME The user name to display. If specified and not empty, the user is only prompted for the password.
By default, credentials are not saved for future use. If they need to be saved, the application has the choice of using the Windows credential manager or saving them in some application-specific (and secure!) manner. In the former case, the -persist option must be specified as true and when the call returns, the credentials must be verified and the validity of the credentials must be communicated to the Windows credentials manager by calling cred_confirm iff the third element of the returned list (indicating the save setting) is true. In the latter case where the Windows credential manager is not being used, the manner of securely saving the credentials is entirely up to the application. In both cases, the user may be given the choice of saving the credentials or not by specifying the -showsaveoption as true. The command cred_prompt_gui provides a GUI version of this command.
cred_prompt_gui TARGET ?options?
Shows a dialog prompting the user for credentials. If the user cancels the dialog, the command returns an empty list. Otherwise, it returns a list of three elements, the user name, the password, and a boolean indicating whether the user selected for the credentials to be saved or not.

The following options may be specified:
-bitmap HANDLE Specifies a hande to a bitmap to be displayed in the dialog. The bitmap dimensions should be 320x60 pixels.
-caption CAPTION Specifies a caption to be displayed in the dialog.
-completeusername BOOLEAN If specified as a true value, the user name component of the return value is of the form TARGET\USERNAME.
-excludecertificates BOOLEAN Does not show certificate-based credentials in the combo box.
-filllocaladmins BOOLEAN Fill the user name combobox with local administrator accounts only.
-forceui BOOLEAN If specified as true, the user is prompted even if the credentials manager already has the requested credentials. Default is false. This option may only be used for generic credentials.
-keepusername BOOLEAN Prefills the user name and does not permit user to change it.
-message MESSAGE Specifies a message to be displayed in the dialog.
-parent HWIN Specifies the handle of a windows to be used as the parent for the dialog.
-password PASSWORD The password to be used as default. PASSWORD must be in the form accepted by reveal which is also the form returned by this command. Plain text passwords are not supported by this command.
-persist BOOLEAN If true, credentials are to be persisted by the credentials manager if so desired by the user. Default is false. If specified as true, cred_confirm must be called with the result of the validation.
-requirecertificate BOOLEAN Only show certificate-based credentials in the combo box.
-requiresmartcard BOOLEAN Only show smartcard-based credentials in the combo box.
-showsaveoption BOOLEAN Specifies whether the user should be given the option to save the credentials. Defaults to false (meaning user is not shown the choice). Note if specified as true but the options -persist is not specified or is false, it is up to the caller to save credentials appropriately by some application-specific means.
-type TYPE Specifies the type of credentials. TYPE must be generic (default), domain or runas. If domain, if the entered user name is not fully qualified, it is returned qualified with TARGET as the domain. If runas, then an unqualified user name is qualified with the name of the system. For generic, user names are returned as entered.
-username USERNAME The user name to display as the default. Defaults to the empty string.
-validateusername BOOLEAN If true, forces the user to choose a user name of the form [email protected] or netbiosname\username.
By default, credentials are not saved for future use. If they need to be saved, the application has the choice of using the Windows credential manager or saving them in some application-specific (and secure!) manner. In the former case, the -persist option must be specified as true and when the call returns, the credentials must be verified and the validity of the credentials must be communicated to the Windows credentials manager by calling cred_confirm iff the third element of the returned list (indicating the save setting) is true. In the latter case where the Windows credential manager is not being used, the manner of securely saving the credentials is entirely up to the application. In both cases, the user may be given the choice of saving the credentials or not by specifying the -showsaveoption as true. The command cred_prompt_console provides a console version of this command.
debuglog ?MESSAGE?
Writes each specified argument as a message to an internal log. There is an internal limit on the number of messages stored. Older messages are discarded once the log reaches this limit. The command must be enabled with debuglog_enable for logging to have effect.
debuglog_clear
Clears the internal debug log.
debuglog_disable
Disables the debuglog command.
debuglog_enable
Enables the debuglog command.
debuglog_get
Returns the current content of the internal debug log.
duplicate_handle HANDLE ?options?
Duplicates an operating system handle. HANDLE may be either in the form returned by commands such as get_tcl_channel_handle or get_process_handle or may be an actual address (integer) literal corresponding to the handle. The following options specify the context of the handle and control attributes of the duplicated handle:
-access ACCESSRIGHTS Specifies the access rights desired for the new handle. If unspecified, the new handle is created with the same access rights as the original one. ACCESSRIGHTS is a list of symbolic constants and bit masks as specified in Access Rights.
-closesource If specified, HANDLE is closed after it is duplicated.
-inherit If specified, the new handle marked as inheritable. By default, the duplicated handle cannot be inherited by child processes.
-sourcepid SOURCEPID Specifies the PID of the process in whose context HANDLE is a valid handle. Defaults to the current process.
-targetpid TARGETPID Specifies the PID of the process in whose context the new handle is to be created. Specifying this also impacts the format of the returned handle value.
If option -targetpid is not specified, the command returns the duplicated handle in symbolic form that can be passed to functions such as close_handle. If -targetpid is specified, the command returns the literal value of the handle. This is true even if the target PID is that of the current process.
export_public_commands
Export public commands in the twapi:: namespace. The commands in the twapi:: namespace are not exported by default.
format_message ?options?
Formats and returns a message string based on a format string. The format string may be directly supplied, obtained from a loaded library or module, or the system message tables. The format string may contain format insert specifiers of the form %N where N is a number between 1 and 99. The format specifier is replaced by the corresponding positional parameter. The format specifier %0 is treated specially as indicating that a newline character is not to be appended to the result. See FormatMessage in the Windows SDK for more details regarding this command including format specifiers. The command takes the following options:
-module MODULE Specifies that the format string is to be loaded from the module identified by MODULE. MODULE may either be a handle returned from a command such as load_library or the path to a DLL. If this option is specified, options -messageid and -langid must also be specified. This option cannot be used with the -fmtstring option.
-fmtstring FORMATSTRING Specifies that FORMATSTRING should be used as the format string for the message. Cannot be used with the -module option.
-messageid MESSAGEID Specifies the message identifier of the format string. This option cannot be used with the -fmtstring option.
-langid LANGID Specifies the language identifier to be used in constructing the message. This option cannot be used with the -fmtstring option.
-includesystem Specifies that the system message tables should also be searched in addition to the message tables in the module specified by -module. This option cannot be used with the -fmtstring option.
-params PARAMLIST Specifies a list of positional parameters that are to be used to replace the %N format insert sequences in the format string. If the number of parameters does not match the number of escape sequences, a Tcl exception may be generated.
-ignoreinserts If specified, the %N format insert sequences are not replaced in the returned string.
-width MAXLINEWIDTH If MAXLINEWIDTH is 0 (default), the returned string contains the same line breaks as in the original format string. The -width option may be used to control the maximum line width in the created message. If MAXLINEWIDTH is between 1 and 254, the command will insert line end characters at appropriate points in the message. In this case, line end characters in the original message are ignored. However, hard coded line end characters, specified as %n in the format string are kept. A MAXLINEWIDTH value of -1 also ignores line end characters while keeping the hard coded %n line end specifiers, but does not insert any line end characters to limit the line length and to terminate the message.
Warning: This command requires all insert placeholders to be strings. Decimal format specifiers such as %|u! will not result in the correct decimal value being inserted.
free_library HMODULE
Frees a loaded module. HMODULE must be a handle previously returned through load_library, get_module_handle or get_module_handle_from_address.
get_build_config ?CONFIGKEY?
If no arguments are specified, returns an dictionary that contains the TWAPI build configuration. If CONFIGKEY is specified, only returns the value for that configuration key. The build configuration keys are:
comobj_ootype The underlying object system on which the TWAPI COM support is built.
compiler The compiler used for the build (e.g. vc++)
compiler_version The version of the build compiler.
opts List of additional options used in the build.
platform One of x86 or x64.
sdk_version Version of the Windows SDK used for the build.
tcl_header_version Version of the Tcl headers used for the build.
tea Boolean indicating whether the build used Tcl Extension Architecture or native builds.
get_handle_inheritance HANDLE
Indicates whether the specified handle is marked as inheritable by child processes.
get_tcl_channel_handle CHANNEL DIRECTION
Returns the operating system handle corresponding to a Tcl channel identifier (for example, returned by the Tcl open command). If DIRECTION is write, the write-side handle is returned, otherwise the read-side handle is returned. (For many channel types, the two are identical.)
get_version ?-patchlevel?
Without any arguments, the command returns the major/minor TWAPI version number in the form MAJOR.MINOR. If the option -patchlevel is specified, the returned string includes patchlevel and release information similar to the Tcl info patchlevel command, for example, 1.0.2 for final release of version 1.0 patch 2, 1.0b3 for the third beta release of version 1.0 and 1.0a3 for the third alpha release of version 1.0.
hex BIN
Returns the binary string BIN as a hexadecimal string.
hex32 INT32VAL
Returns INT32VAL as a fixed width hexadecimal string.
hex64 INT64VAL
Returns INT64VAL as a fixed width hexadecimal string.
import_commands
Imports all public commands in the twapi:: namespace into the caller's namespace.
is_valid_sid_syntax sid
Returns true or false depending on whether sid is a valid SID or not. Note this only checks the syntax of the SID, not whether it corresponds to a real account.
lambda ARGLIST BODY ?NAMESPACE?
Simple wrapper that returns an anonymous proc definition based on the Tcl apply command.
large_system_time_to_secs_since_1970 SYSTEMTIMEVALUE ?BOOLEAN?
Some Windows functions return time as the number of 100 nanosecond units since Jan 1, 1601. The command converts such time values to seconds since the epoch Jan 1, 1970. If BOOLEAN is false (default), an integral number of seconds is returned. Otherwise, the fractional part is also returned.
large_system_time_to_timelist SYSTEMTIMEVALUE
Some Windows functions return time as the number of 100 nanosecond units since Jan 1, 1601. The command converts such time values to a list of 8 elements representing the year, month, day, hour, minutes, seconds, milliseconds and day of week.
load_library FILEPATH ?options?
Loads a DLL and returns a handle to it. The handle must later be released by calling free_library, not close_handle. The following options may be specified:
-dontresolverefs Normally, if the module being loaded is a DLL, the system will load any other modules referenced by it and also call its DllMain function to initialize it. If this option is specified, neither of these actions will be done.
-datafile If specified, the module is loaded as a data file as opposed to an executable module. This is useful when the file is being loaded only to extract resources or format messages.
-alteredpath Uses an alternative search strategy to find modules referenced by this module. See the Windows SDK for more details.


See LoadLibraryEx in the Windows SDK for more details regarding this command.
lookup_account_name name ?options?
name specifies the name of the account and may be fully qualified in the form domain\name.

If no options are specified, this command returns the SID for the account. If one or more options are specified, returns a flat list of the form "option1 value1 ...". The following options may be specified:
-all Returns all values.
-sid Returns the SID for the account.
-domain Returns the domain in which the account was found.
-system Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.
-type Returns the account type. This may be one of user, group (domain group), domain, alias (system local group), logonid, wellknowngroup, deletedaccount, invalid, unknown, computer or label. The logonid type is returned for SID's that identify a logon session.
lookup_account_sid sid ?options?
Argument sid specifies the SID of the account. If no options are specified, this command returns the name for the account. If one or more options are specified, the command returns a flat list of the form "option1 value1 ...". The following options may be specified:
-all Returns all values.
-name Returns the name for the account.
-domain Returns the domain in which the account was found.
-system Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.
-type Returns the account type. This may be one of user, group (domain group), domain, alias (system local group), wellknowngroup, deletedaccount, invalid, unknown, logonsession or computer.
make_logon_identity USERNAME PASSWORD DOMAIN
Returns a descriptor containing credentials to be used for authenticating in a form required by several other commands. PASSWORD may be either plaintext or in encrypted form as returned by by the credentials_prompt, credentials_dialog or conceal commands.
map_account_to_name ACCOUNT ?-system SYSTEMNAME?
Returns the name for an account. If ACCOUNT is a valid account name, it is returned as is. Otherwise, it is assumed to be a SID and the corresponding account name is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.
map_account_to_sid ACCOUNT ?-system SYSTEMNAME?
Returns the SID corresponding to an account. If ACCOUNT is a SID, it is returned as is. Otherwise, it is assumed to be an account name and the corresponding SID is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.
map_windows_error ERRORCODE
Returns the text string corresponding to a Windows error code.
new_uuid ?-localok?
Returns a UUID. If the system does not contain a network card, the operating system may return an error as it cannot guarantee uniqueness across systems. Specifying the -localok option causes this to be ignored and a identifier value to be returned anyways.
nil_uuid
Returns a nil UUID.
new_guid
Returns a GUID.
parseargs ARGLISTVAR OPTLIST ?-ignoreunknown? ?-nulldefault? ?-hyphenated? ?-maxleftover MAXLEFTOVER? ?-setvars?
Parses the options specified in a list of arguments. ARGLISTVAR is the name of a variable in the caller's scope that contains a list of arguments. Option names are case-sensitive and begin with a - character. Option processing is terminated when an argument does not begin with a leading - or is one of the special - or --.

OPTLIST specifies the valid options allowed and is list of option specifiers. Each option specifier is a list of up to 3 elements and takes the following form:

OPTNAME?.OPTTYPE? ?DEFAULTVALUE ?VALUEOPTS??

OPTNAME is the name of the option (without a leading -) and is required. OPTTYPE should be separated from the name with a . and specifies the type of the option. It must have one of the following values: arg, bool, int, sym or switch. In the first three cases, the argument following the option is taken as the value of the option and must be of an appropriate type: an arbitrary string, a boolean value (0, 1, off, on, false, true) or an integer respectively. If OPTTYPE is sym, the the option value is expected to be an integer or a a key into the dictionary VALUEOPTS and the returned value of the option is the mapped value from this dictionary. If the option type is switch, or is not specified at all, then the option is not associated with any value and is treated as a binary switch.

DEFAULTVALUE, specifies a default value to be assumed for the option if it is not present in ARGLISTVAR. This is ignored for options of type switch.

If VALUEOPTS is specified for option types arg or int, it is treated as a list of allowed values for the option. If an option's value is not in the list, the command will return an error. For option type sym, VALUEOPTS is a dictionary as described previously. If the option type is bool or switch, VALUEOPTS is the treated as the value to return when the value of the option is boolean true (by default 1 is returned). This is commonly used in TWAPI to return a integer bit mask for the true value of an option.

If the option -setvars is not specified, the command returns a list of the form OPTION VALUE OPTION VALUE.... If the -hyphenated option is not specified, the OPTION fields in the returned value contain the option name without a leading - character. If the -hyphenated option is specified, OPTION includes the leading - character. This is useful when options are passed through to other commands after partial processing.

If the option -setvars is specified, the command sets variables with the names of the specified options to the corresponding values. The command returns an empty string in this case.

If the -nulldefault option is not present, only options that are present in ARGLISTVAR, or have a default value specified, or are of type switch are included in the returned result. If the -nulldefault option is present, then the returned list also includes values for options that are not present - 0 for options of type int and bool, and an empty string for arguments of type arg.

As a side effect, the variable ARGLISTVAR is modified to remove the parsed options and associated values. If the -maxleftover option is specified, the command will raise a Tcl error if the number of arguments left over after parsing the options is more than MAXLEFTOVER.

The command will normally generate a Tcl error if the arguments include an unknown option (an argument that begins with a - character and is not in OPTLIST). If the -ignoreunknown option is specified to the command, unknown options in ARGLISTVAR are ignored instead of an error being generated and are not removed from ARGLISTVAR.
random_bytes NUMBER
Returns the specified number of random bytes. This is a call into the RtlGenRandom Win32 API.
read_credentials ?options?
Deprecated. Use credentials_prompt.
recordarray cell RECORDARRAY INDEX FIELD
Returns the value of the field FIELD of the record at index INDEX in the specified record array.
recordarray column RECORDARRAY FIELD ?-filter FILTERLIST?
Returns a list of values of the field FIELD in all records. If option -filter is specified only the values from the matching records are included in the returned list. See Record arrays for the format of FILTERLIST.
recordarray concat ?RECORDARRAY RECORDARRAY...?
Returns a record array containing records from one or more record arrays. The fields in each record array must be the same.
recordarray fields RECORDARRAY
Returns field names for the records in the record array.
recordarray get RECORDARRAY ?options?
Returns a record array containing a subset of the records and fields from RECORDARRAY. options may be include -filter and -slice from amongst the standard options described in Record arrays. Other options are silently ignored.
recordarray getdict RECORDARRAY ?options?
Returns a dictionary containing a subset of the records and fields from RECORDARRAY. The keys of the dictionary are specified through option -key the value for which must be the name of a field in the dictionary. If the option is not specified, the first field in the record definition for the record array is used as the key. options may include any of the standard options described in Record arrays.
recordarray getlist RECORDARRAY ?options?
Returns a list containing a subset of the records and fields from RECORDARRAY. The form and content of the elements of the returned list depend on the options as described in Record arrays.
recordarray index RECORDARRAY INDEX ?options?
Returns the record at a specified position in the record array. The options -format and -slice as described in Record arrays control the fields returned and their format.
recordarray iterate ARRAYVAR RECORDARRAY ?options? BODY
Iterates over all records in a recordarray. For each record, sets the array variable ARRAYVAR to the current record and evaluates BODY in the caller's context. The keys of ARRAYVAR are the field names of the record array.

options may include the -slice and -filter options as described in Record arrays.
recordarray range RECORDARRAY LOW HIGH
Returns a new record array containing the records in the specified index range.
recordarray rename RECORDARRAY FIELDRENAMEMAP
Returns a new record array with the same records as RECORDARRY but with the fields renamed as per the contents of the dictionary FIELDRENAMEMAP which should map the old field name to a new one. Names of any fields not in FIELDRENAMEMAP are preserved.
recordarray size RECORDARRAY
Returns the number of records in the record array.
rethrow
Raises a Tcl error where the error options, including values of errorCode and errorStack, are the same as when an exception was raised inside a trap command. This command can only be used inside a onerror clause of a trap and is useful to regenerate the original error when the error handler cannot handle the exception.
reveal ENCRYPTED
Decrypts a binary string that was encrypted by conceal within the same process.
safearray TYPE LISTVALUE
Returns LISTVALUE in a form that is interpreted by COM related commands as a single-dimensioned safearray of type TYPE. TYPE must be one of the COM types bool, int or i4, double or r8, bstr, or variant.
secs_since_1970_to_large_system_time SECONDS
This command converts SECONDS which is the number of seconds since the epoch Jan 1, 1970 to the number of 100 nanoseconds since Jan 1, 1601.
set_handle_inheritance HANDLE BOOLEAN
If BOOLEAN is true, HANDLE is marked as being inheritable by child processes. If false, the handle will not be inherited.
swap2 BYTES2
Byte swaps a 16 bit value.
swap4 BYTES4
Byte swaps a 32 bit value.
swap8 BYTES8
Byte swaps a 64 bit value.
timelist_to_large_system_time TIMELIST
Converts TIMELIST to the number of 100 nanoseconds since Jan 1, 1601. If TIMELIST is an empty list, it defaults to the current date and time. Otherwise it is a list of 3-7 elements that specify the year, month, day, hours, minutes, seconds and milliseconds. The last four are optional and default to 0. TIMELIST must be a list of 7 elements representing the year, month, day, hour, minutes, seconds and milliseconds.
tclcast TYPE VALUE
Returns VALUE whose internal Tcl type is set to TYPE. See Controlling Parameter Types for a use case. TYPE must be one of empty, null, bstr, (corresponding to COM VARIANT types VT_EMPTY, VT_NULL and VT_BSTR), or one of the Tcl internal types int, boolean, double, string, list, or dict.
tcltype VALUE
Returns the internal Tcl type for a value.
trap SCRIPT ?onerror ERRORPATTERN ERRORSCRIPT?... ?finally FINALSCRIPT?
The command executes SCRIPT in the caller's context. If the script completes without generating any Tcl exceptions, the command executes the script FINALSCRIPT if specified. The result of the command is the result of SCRIPT.

If SCRIPT generates any errors, the command matches the Tcl global ::errorCode variable against each specified ERRORPATTERN in turn. When the first match is found, the corresponding ERRORSCRIPT is executed. Then FINALSCRIPT is executed if specified. The return value from the command is the result of the executed ERRORSCRIPT script.

If the none of the ERRORPATTERN arguments match when an error occurs in SCRIPT, the command executes FINALSCRIPT if specified, and then regenerates the original error.

Each ERRORPATTERN should be a list and is matched against the first (facility) and second (code) elements of ::errorCode. If ERRORPATTERN is empty, it matches any value of ::errorCode. If ERRORPATTERN contains only one element, it is matched against the first element of ::errorCode with the second field of ::errorCode not used for matching. When matching against the second element of ::errorCode, first a exact string match is tried and if that fails, an integer match is tried if both operands being compared are valid integers.

Within an onerror clause, the command rethrow may be used to raise the error that was caught by the clause. This is useful when an error handler finds it cannot handle the case and wants to raise the original error. Similarly, the trapresult and trapoptions commands can be used in a onerror clause to retrieve the error message and error options dictionary captured by the onerror clause.
wait_on_handle HANDLE ?options?
The command waits on the specified HANDLE until it is either signalled or a timeout expires. The command can also be used for non-blocking asynchronous notification. HANDLE may be any operating system handle for which Windows supports the WaitForSingleObject API.

WARNING: HANDLE must NOT be closed while it is being waited on. Windows behaviour is undefined in this case and may result in a program crash.

The command may return one of the following values if the -async option is not specified: signalled, timeout, abandoned. If -async is specified, the command returns an empty string and the result is passed to the callback script instead.

The following options may be specified:
-wait MILLISECS Specifies the number of number of milliseconds to wait for the handle to be signalled. The default is -1 which indicates no timeout.
-async SCRIPT If specified, the command returns immediately. SCRIPT is then invoked when the handle is signalled or the timeout specified through -wait has elapsed. Note that if a timeout is specified with the -wait option, the timeout does not cancel the wait and the script is invoked repeatedly every MILLISECONDS if the handle is not signalled.

Two additional arguments are appended to SCRIPT - HANDLE and the return value (signalled etc.). Once a handle is registered for asynchronous notification, it must not be used for synchronous notification unless the asynchronous notification is first canceled through the cancel_wait_on_handle command. If the handle was already registered for asynchronous notification, the previously registered script is replaced with SCRIPT.
-executeonce BOOLEAN If this option is specified as true, the SCRIPT is executed only once, even if the object HANDLE stays in a signalled state. Default is false. This option is ignored if -async is not specified.
win32_error WINERROR ?MESSAGE?
Generates a Tcl exception corresponding to the Windows error code WINERROR. MESSAGE may be specified as the error message in which case the system error message for WINERROR is appended to it.

COPYRIGHT

Copyright © 2004-2012 Ashok P. Nadkarni

Tcl Windows API 4.6.0