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

NAME

httpd::doc - File handling

SYNOPSIS

package require httpd::doc ?1.1?

Doc_AddRoot virtual directory arg...
Doc_Root ?real arg...?
Doc_RegisterRoot virtual directory
Doc_Include filename
Doc_PublicHtml ?homedir?
Doc_Virtual sock curfile virtual
Doc_Handle prefix path suffix sock

DESCRIPTION

The package httpd::doc provides a domain for the serving of urls from the filesystem. This is also the domain through which the TML template facility is made available. It has additional tie-ins to the packages httpd::cgi (CGI applications stored in the fileststem) and httpd::dirlist (Directory listings as virtual files).

Public API

Access control
This package installs an access control callback, DocAccessControl which uses the package httpd::auth to determine if an request for an url has to be denied or not. This method searches the directory path to the file for .htaccess or .tclaccess files that specify access controls. These are explained in the /access/ area of the default web site distributed with the server.

Doc_AddRoot virtual directory arg...
This commands adds a mapping from the url prefix virtual to the directory in the filesystem. Any additional arguments will be given as options and values to the internal Url_PrefixInstall call registering virtual as a new domain. Note: The last implies that from httpd::url's point of view each document root is a separate url domain.

Doc_Root ?real arg...?
A convenient wrapper around Doc_AddRoot. It not only installs the directory real as a document domain, but associates it with the root of the url tree on this server, i.e. "/".

The command will return the name of the directory of that document root if no argument is specified. Otherwise it will set this document root and return the empty string.

All arguments coming after are additional options and values which are given to Url_PrefixInstall.

Doc_RegisterRoot virtual directory
Use this call to add a file system managed by any Domain Handler (e.g. CGI for example) to this package. This registers the mapping from urls in the domain to files, as required for Doc_Virtual.

Doc_Include filename
Reads the contents of the file filename and substitutes them via subst at the tcl stack level at which this procedure was called. The result of the substitution is returned as the result of the command. A relative path will be joined with the directory at the top of the include stack in global variable page(includeStack).

Doc_PublicHtml ?homedir?
En- and disables the handling of urls of the form "~user/a/b/..." by mapping them to the subdirectory homedir of that users account. The command will by default use the subdirectory "public_html" if no directory was specified explicitly. To disable the mapping invoke the command using the empty string for the name of the subdirectory.

Doc_Virtual sock curfile virtual
This command looks up the url virtual and returns the associated path in the filesystem. It will return the empty string if virtual is not managed by this package.

If virtual is a relative url, then curfile has to be specified and will be treated as the path of the dcoument containing the reference to virtual.

The argument sock represents the current connection. It is not used by the command.

Doc_Handle prefix path suffix sock
The main command for the handling of document urls. Exported for use by other domains which have to handle files. The first three arguments specify the url to handle, and the file associated with it. The last argument is the connection making the request. The command assumes that all these pieces actually match up with each other.

The command directs requests for directories always to the package httpd::dirlist. Otherwise it will determine the mime-type of the requested document and then either invoke a special handler for that type if such present or directly reply with the contents of that file if there is no special handler for the type.

If the path does not exist in the filesystem then it will try to find an alternative it can serve. A not-found reply will be generated only if that fails too. It is this fallback mechanism which calls the template facility when necessary.

The handler mechanism described above is also dependent on the existence of appropriate file extension to mime type mapping in the package httpd::mtype as otherwise special files will not be recognized as such, i.e. the chosen mime type will be wrong. If a file "mime.types" is present in the server library directory (residence of all packages) it will be read automatically during startup and used to set up a number of standard mappingsa to support the type specific handlers exported by the various server packages.

SEE ALSO

httpd, httpd::auth, httpd::cgi, httpd::cookie, httpd::dirlist, httpd::doc_error, httpd::fallback, httpd::mtype, httpd::url

KEYWORDS

documents, filesystem, web server

COPYRIGHT

Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>