By default, a slave interpreter that loads Tk gets a new top-level window. Wish supports a -use command line option that directs Tk to use an existing window as dot. You can use this to embed an application within another. For example, the following commands run a copy of Wish that uses the .embed toplevel as its main window:

toplevel .embed
exec wish -use [winfo id .embed] somescript.tcl &

More often, embedding is used with child interpreters. If the interpreter is not safe, you can set the argv and argc variables in the slave before loading Tk:

interp create trustedTk
interp eval trustedTk 
     [list set argv [list -use [winfo id .embed]]]
interp eval trustedTk [list set argc 2]
load {} Tk trustedTk

If the child interpreter is safe, then you cannot set argv and argc directly. The easiest way to pass -use to a safe interpreter is with the safe::loadTk command:

safe::interpCreate safeTk
safe::loadTk safeTk -use [winfo id .embed]

When Tk is loaded into a safe interpreter, it calls back into the master interpreter and evaluates the safe::TkInit procedure. The job of this procedure is to return the appropriate argv value for the slave. The safe::loadTk procedure stores its additional arguments in the safe::tkInit variable, and this value is retrieved by the safe::TkInit procedure and returned to the slave. This protocol is used so that a safe interpreter cannot attempt to hijack the windows of its master by constructing its own argv variable!

When Tk is loaded into a safe interpreter, it hides several Tk commands. Primarily these are hidden to prevent denial of service attacks against the main process. For example, if a child interpreter did a global grab and never released it, all input would be forever directed to the child. Table 20-1 lists the Tk commands hidden by default from a safe interpreter. The Tcl commands that are hidden in safe interpreters are listed on page 295.

If you find these restrictions limiting, you can restore commands to safe interpreters with the interp expose command. For example, to get menus and toplevels working, you could do:

interp create -safe safeTk
foreach cmd {grab menu menubutton toplevel wm} {
    interp expose safeTk $cmd
}

Instead of exposing the command directly, you can also construct aliases that provide a subset of the features. For example, you could disable the -global option to grab. Aliases are described in detail in Chapter 19.

The Browser plugin defines a more elaborate configuration system to control what commands are available to slave interpreters. You can have lots of control, but you need to distribute the security policies that define what Tclets can do in the plugin. Configuring security policies for the plugin is described later.

The parameters in the EMBED tag are available to the Tcl program in the embed_args variable, which is an array with the parameter names as the index values. For example, the string for a ticker-tape Tclet can be passed in the EMBED tag as the string parameter, and the Tclet will use $embed_args(string) as the value to display:

<EMBED src=ticker.tcl width=400 height=50 string="Hello World">

Note that HTML tag parameters are case sensitive. Your Tclet may want to map all the parameter names to lowercase for convenience:

foreach {name value} [array get embed_args] {
   set embed_args([string tolower $name]) $value
}

The plugin array has version, patchLevel, and release elements that identify the version and release date of the plugin implementation.

The plugin home page is a great place to find Tclet examples. There are several plugins done by the Tcl/Tk team at Sunlabs, plus links to a wide variety of Tclets done on the Net.

My first plugin was calculator for the effective wheel diameter of multigear bicycles. Brian Lewis, who built the Tcl 8.0 byte-code compiler, explained to me the concept and how important this information is to bicycle enthusiasts. The Tclet that displays the gear combinations on a Tk canvas and lets you change the number of gears and their size. You can find the result at:

There are plugin versions for UNIX, Windows, and Macintosh. The installation details vary somewhat between platforms and between releases of the plugin. The following components make up the plugin installation:

The browser package is bundled with several of the security policies. It makes many features of the Web browser accessible to Tclets. They can fetch URLs and display HTML in frames. However, the browser package has some risks associated with it. HTTP requests can be used to transmit information, so a Tclet using the policy could leak sensitive information if it can fetch a URL outside the firewall. To avoid information leakage, the inside, outside, and home policies restrict the URL that can be fetched with browser::getURL. Table 20-2 lists the aliases defined by the browser package.

The browser::getURL function uses the browser's built-in functions, so it understands proxies and supports ftp:, http:, and file: urls. Unfortunately, the browser::getURL interface is different from the http::geturl interface. It uses a more complex callback scheme that is due to the nature of the browser's built-in functions. If you do not specify any callbacks, then the call blocks until all the data is received, and then that data is returned. The callback functions are described in Table 20-3.

The main configuration file is the config/plugin.cfg file in the plugin distribution. This file lists what features are supported by the plugin, and it defines the URL filters for the trust map.

The configuration file is defined into sections with a section command. The policies section defines which Tclets can use which security policies. For example, the default configuration file contains these lines in the policies section:

section policies
    allow home
    disallow intercom
    disallow inside
    disallow outside
    disallow trusted
    allow javascript ifallowed trustedJavaScriptURLS 
          $originURL

This configuration grants all Tclets the right to use the home policy, disallows all Tclets from using the intercom, inside, outside, and trusted policies, and grants limited access to the javascript policy. If you are curious, the configuration files are almost Tcl, but not quite. I lost an argument about that one, so these are stylized configuration files that follow their own rules. For example, the originURL variable is not defined in the configuration file but is a value that is tested later when the Tclet is loaded. I'll just give examples here and you can peer under the covers if you want to learn how they are parsed.

The ifallowed clause depends on another section to describe the trust mapping for that policy. For the javascript policy, the config/plugin.cfg file contains:

section trustedJavascriptURLs
    allow http://sunscript.sun.com:80/plugin/javascript/*

Unfortunately, this server isn't running anymore, so you may want to add the Scriptics Web server to your own configuration:

allow http://www.tcl.tk:80/plugin/javascript/*

You can use a combination of allow and disallow rules in a section. The arguments to allow and disallow are URL string match patterns, and they are processed in order. For example, you could put a liberal allow rule followed by disallow rules that restrict access, or vice versa. It is probably safest to explicitly list each server that you trust.

Each security policy has a configuration file associated with it. For example, the outside policy uses the file outside.cfg file in the config directory. This file specifies what hosts and ports are accessible to Tclets using the outside policy. For the inside and outside policies, the configuration files are similar in spirit to the safesock array used to configure the Safesock security policy shown on page 302. There are a set of allowed hosts and ports, and a set of excluded hosts. The excluded hosts are an exception list. If a host matches the included set but also matches the excluded set, it is not accessible. There is an included and excluded set for URLs that affect browser::geturl. The settings from the Tempfile policy shown on page 304 are also part of the home, inside, and outside configuration files. The configuration files are well commented, and you should read through them to learn about the configuration options for each security policy.

The aliases that make up a security policy are organized into sets called features. The features are listed in the main config/plugin.cfg configuration file:

variable featuresList {url stream network persist unsafe}

In turn, each security policy configuration file lists what features are part of the policy. For example, the config/home.cfg file lists these features:

section features
    allow url
    allow network
    allow persist unless {[string match {UNKNOWN *} 
        [getattr originURL]]}

Each feature is implemented in a file in the safetcl directory of the distribution. For example, the url feature is implemented in safetcl/url.tcl. The code in these files follows some conventions in order to work with the configuration mechanism. Each one is implemented inside a namespace that is a child of the safefeature namespace (e.g., safefeature::url). It must implement an install procedure that is called to initialize the feature for a new Tclet. It is inside this procedure that the various allow/disallow rules are checked. The cfg::allowed command supports the rule language used in the .cfg files.

This book does not describe the details of the configuration language or the steps necessary to create a new security policy. There are several manual pages distributed with the plugin that explain these details. They can be found on the Web at:

If you are serious about tuning the existing security policies or creating new ones, you should read the existing feature implementations in detail. As usual, modifying a working example is the best way to proceed! I think it is a very nice property of the plugin that its security policies are implemented in Tcl source code that is clearly factored out from the rest of the Tcl/Tk and plugin implementation. With a relatively small amount of code, you can create custom security policies that grant interesting abilities to Tclets.