Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 18.  TclHttpd Web Server

Programming Reference

This section summarizes many of the more useful functions defined by the server. These tables are not complete, however. You are encouraged to read through the code to learn more about the features offered by the server.

Table 18-1 summarizes the Httpd functions used when returning pages to the client.

Table 18-1. Httpd support procedures.
Httpd_Error sock codeReturns a simple error page to the client. The code is a numeric error code like 404 or 500.
Httpd_ReturnData sock type dataReturns a page with Content-Type type and content data.
Httpd_ReturnFile sock type fileReturns a file with Content-Type type.
Httpd_Redirect newurl sockGenerates a 302 error return with a Location of newurl.
Httpd_SelfUrl urlExpands url to include the proper http://server:port prefix to reference the current server.

Table 18-2 summarizes a few useful procedures provided by the Url module (url.tcl). The Url_DecodeQuery is used to decode query data into a Tcl-friendly list. The Url_Encode procedure is useful when encoding values directly into URLs. URL encoding is discussed in more detail on page 249

Table 18-2. Url support procedures.
Url_DecodeQuery queryDecodes a www-url-encoded query string and return a name, value list.
Url_Encode valueReturns value encoded according to the www-url-encoded standard.
Url_PrefxInstall prefix callbackRegisters callback as the handler for all URLs that begin with prefix. The callback is invoked with two additional arguments: sock, the handle to the client, and suffix, the part of the URL after prefix.

The Doc module provides procedures for configuration and generating responses, which are summarized in Tables 18-3 and 18-4 respectively

Table 18-3. Doc procedures for configuration.
Doc_Root ?directory?Sets or queries the directory that corresponds to the root of the URL hierarchy.
Doc_AddRoot virtual directoryMaps the file system directory into the URL subtree starting at virtual.
Doc_ErrorPage fileSpecifies a file relative to the document root used as a simple template for error messages. This is processed by DocSubstSystem file in doc.tcl.
Doc_CheckTemplates howIf how is 1, then .html files are compared against corresponding .tml files and regenerated if necessary.
Doc_IndexFile patternRegisters a file name pattern that will be searched for the default index file in directories.
Doc_NotFoundPage fileSpecifies a file relative to the document root used as a simple template for page not found messages. This is processed by DocSubstSystem file in doc.tcl.
Doc_PublicHtml dirnameDefines the directory used for each users home directory. When a URL like ~user is specified, the dirname under their home directory is accessed.
Doc_TemplateLibrary directoryAdds directory to the auto_path so the source files in it are available to the server.
Doc_TemplateInterp interpSpecifies an alternate interpreter in which to process document templates (i.e., .tml files.)
Doc_Webmaster ?email?Sets or queries the email for the Webmaster.

Table 18-4. Doc procedures for generating responses.
Doc_Error sock errorInfoGenerates a 500 response on sock based on the template registered with Doc_ErrorPage. errorInfo is a copy of the Tcl error trace after the error.
Doc_NotFound sockGenerates a 404 response on sock by using the template registered with Doc_NotFoundPage.
Doc_Subst sock file ?interp?Performs a subst on the file and return the resulting page on sock. interp specifies an alternate Tcl interpreter.

The Doc module also provides procedures for cookies and redirects that are useful in document templates. These are described in Table 18-5.

Table 18-5. Doc procedures that support template processing.
Doc_Coookie nameReturns the cookie name passed to the server for this request, or the empty string if it is not present.
Doc_DynamicTurns off caching of the HTML result. Meant to be called from inside a page template.
Doc_IsLinkToSelf urlReturns 1 if the url is a link to the current page.
Doc_Redirect newurlRaises a special error that aborts template processing and triggers a page redirect to newurl.
Doc_SetCookie -name name -value value -path path -domain domain -expires dateSets cookie name with the given value that will be returned to the client as part of the response. The path and domain restrict the scope of the cooke. The date sets an expiration date.

Table 18-6 describes the form module that is useful for self-posting forms, which are discussed on page 259

Table 18-6. The form package.
form::data nameReturns the value of the form value name, or the empty string.
form::empty nameReturns 1 if the form value name is missing or zero length.
form::value nameReturns name="name" value="value", where value comes from the query data, if any.
form::checkvalue name valueReturns name="name" value="value" CHECKED, if value is present in the query data for name. Otherwise, it just returns name="name" value="value".
form::radiovalue name valueReturns name="name" value="value" CHECKED, if the query data for name is equal to value. Otherwise, it just returns name="name" value="value".
form::select name valuelist argsGenerates a select form element with name name. The valuelist determines the option tags and values, and args are optional parameters to the main select tag.

Table 18-7 shows the initial elements of the page array that is defined during the processing of a template.

Table 18-7. Elements of the page array.
queryThe decoded query data in a name, value list.
dynamicIf 1, the results of processing the template are not cached in the corresponding .html file.
filenameThe file system pathname of the requested file (e.g., /usr/local/htdocs/tclhttpd/index.html).
templateThe file system pathname of the template file (e.g., /usr/local/htdocs/tclhttpd/index.tml).
urlThe part of the url after the server name (e.g., /tclhttpd/index.html).
rootA relative path from the template file back to the root of the URL tree. This is useful for creating relative links between pages in different directories.

Table 18-8 shows the elements of the env array. These are defined during CGI requests, application-direct URL handlers, and page template processing:

Table 18-8. Elements of the env array.
AUTH_TYPEAuthentication protocol (e.g., Basic).
CONTENT_LENGTHThe size of the query data.
CONTENT_TYPEThe type of the query data.
DOCUMENT_ROOTFile system pathname of the document root.
GATEWAY_INTERFACEProtocol version, which is CGI/1.1.
HTTP_ACCEPTThe Accept headers from the request.
HTTP_AUTHORIZATIONThe Authorization challenge from the request.
HTTP_COOKIEThe cookie from the request.
HTTP_FROMThe From: header of the request.
HTTP_REFERERThe Referer indicates the previous page.
HTTP_USER_AGENTAn ID string for the Web browser.
PATH_INFOExtra path information after the template file.
PATH_TRANSLATEDThe extra path information appended to the document root.
QUERY_STRINGThe form query data.
REMOTE_ADDRThe client's IP address.
REMOTE_USERThe remote user name specified by Basic authentication.
REQUEST_URIThe complete URL that was requested.
SCRIPT_NAMEThe name of the current file relative to the document root.
SERVER_NAMEThe server name, e.g., www.beedub.com.
SERVER_PORTThe server's port, e.g., 80.
SERVER_PROTOCOLThe protocol (e.g., http or https).
SERVER_SOFTWAREA software version string for the server.

      Previous section   Next section