Handles

Commands for managing operating system handles

SYNOPSIS

package require twapi

cancel_wait_on_handle HANDLE

close_handle HANDLE

create_file PATH ?options?

duplicate_handle HANDLE ?options?

get_tcl_channel_handle CHANNEL DIRECTION

wait_on_handle HANDLE ?options?

DESCRIPTION

This module provides commands that deal with operating system handles.

Overview

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.

Commands

cancel_wait_on_handle HANDLE

Cancels any previously registered asynchronous wait on a handle that was registered using wait_on_handle.

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

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.

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.

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

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.

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.

COPYRIGHT

Copyright © 2004-2009 Ashok P. Nadkarni