httpd::direct(n) 1.1 "Tcl Web Server"

NAME

httpd::direct - Application direct domains

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    Public API
    SEE ALSO
    KEYWORDS
    COPYRIGHT

SYNOPSIS

package require httpd::direct ?1.1?

Direct_Url virtual ?prefix? ?inThread?

Direct_UrlRemove prefix

The package httpd::direct provides generic facilities for the implementation of application direct domains. These are domains where each url in the domain is handled by its own tcl command. Urls for which there is no command to handle it do not exists and cause the generation of an http error reply.

Public API

Direct_Url virtual ?prefix? ?inThread?

Registers the url prefix virtual as an application direct domain. If prefix is used then it declares the command prefix to use when constructing the name of the tcl command handling a particular url (See below for more details). If either no such prefix is declared, or as the empty string, then the url prefix itself, i.e. virtual, will be used as the basename of the handler command. The last argument specifies whether the handlers command should run in a separate thread. By default the main thread is used.

Regarding the construction of tcl commands for handling particular urls: For each url a/b/c in the domain the system will construct the command name prefix/a/b/c and call this to generate the html for that url. The value of any form variable for which the procedure has an argument of the same name will be assigned to that argument. All remaining form variables and their values will be appended to the command in the form (varname value)... This means that any command implementing an application direct domain has to have an args argument to capture this data and prevent errors in this package when the command is called.

The same data is also available through the commands provided by the package ncgi.

The return code of the handler has important meaning. Anything outside of a regular return (code 0) and code 302 will be treated as an exception and thrown upward. As for the two codes mentioned above:

0

A regular return. The return value of the handler command is used as the data to return to the browser. By default it is treated as of type "text/html". This can be changed by defining a global variable of the same name as the handler command and assigning the correct mime content type to it. I.e.

set prefix/a/b/c text/plain

302

This code causes the package to assume that the result of the handler command is an url, and causes the generation of a http redirect reply to that url. (Side note: 302 is also the http protocol code used in http redirect replies).

Handlers for application direct domains are not given explicit access to either the channel handle for the connection, nor the connection status array. However they can use upvar to import sock or data respectively from the caller's scope, which contain this information.

Direct_UrlRemove prefix

Removes the application direct domain which was registered for the specified command prefix.

KEYWORDS

application direct, domain, web server