Safe-Tcl - stream manual page

The stream feature is installed into a Safe-Tcl interpreter by a security policy that enables the feature. This policy is called the controlling security policy, below. The stream featue adds aliases to a Safe-Tcl interpreter to allow it to invoke JavaScript commands, generate output to a frame as encodd by a mime type, and to send electronic mail.

The procedures added by the stream feature are discussed in the PROCEDURES section. The CONFIGURATION section describes how to control the behavior of this feature at runtime. The risks associated with the feature are described the SECURITY section.

PROCEDURES

The stream feature provides these procedures:

::browser::openStream frame ?mimeType?: This procedure opens a stream to a frame frame managed by the hosting application and returns the name of the new stream. Data sent to the stream is interpreted as having the mime type mimeType, which defaults to text/html. The name of the stream is returned. The frame names _self, _current and the empty string are disallowed, because their use causes data sent on the stream to replace the contents of the frame containing the Tclet, which causes some hosting applications to operate incorrectly. See the description of the ::browser::displayURL procedure in the manual page for the url feature for details on other special names. If the frame frame does not exist, it is created with the current default size, toolbar decorations and location for the hosting application. Otherwise, the current contents of the frame are discarded and the frame is repainted with the current default background color for the hosting application.
::browser::closeStream stream: Closes the stream stream which was previously opened with ::browser::openStream. Subsequently, calling ::browser::writeToStream with this stream returns an error.
::browser::writeToStream stream data: Writes data to the stream which must be the name of a stream previously opened with ::browser::openStream.
::browser::javascript javascriptCmd ?callback?: This procedure sends a JavaScript command for execution by the hosting application, and receives the result if one is produced. Some JavaScript computations do not produce a result and hence no result is returned for them by this procedure. If an error results from the JavaScript command, the error is returned by this command. If callback is not given, the operation blocks until the JavaScript computation completes, or until a timeout occurs. If the optional callback is given, the procedure returns immediately and arranges for callback to be called when the computation finishes or times out. The callback argument is explained below. This procedure is dangerous because it gives access to all of JavaScript's capabilities.
callback name stream reason data: The ::browser::javascript procedure accepts an optional callback that will be called when the result of the JavaScript computation arrives from the hosting application. It is invoked with the same arguments as the endCallback explained in the manual page for the url feature.
::browser::email recipients text: This procedure sends electronic mail to a comma-separated list of recipients with content text. Because of limitations in the APIs of hosting applications, a subject field or other common header fields can not be specified. This procedure is dangerous because it allows untrusted Tcl programs to send electronic mail using the user's originating address. It is enabled only by the javascript policy.

CONFIGURATION

If a specific alias is not allowed in the aliases section of a controlling policy's configuration, it will not be installed into a Tclet when using this policy. This allows a policy to enable or disable each alias individually.

SECURITY

This feature allows a Tclet to send electronic mail, call arbitrary JavaScript code, and generate streams to frames managed by the hosting application without filtering the data sent. The ability to send electronic mail exposes the user to loss of reputation and privacy risks. Because JavaScript is an evolving language, and because its use together with arbitrary Tclet code is not well understood, one must assume the worst about the risks that the user is exposed to.

For these reasons, the stream feature is allowed only in the javascript and trusted policies. These policies are themselves disabled by default; it is highly recommended that they be enabled only for Tclets that are trusted by the user.

KEYWORDS

JavaScript, electronic mail, HTML generation, frames

Tcl Plugin 2.0