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. A simple naming convention is used to distinguish procedures that are private to a file (e.g., HttpdEvent) and procedures that are meant to be used by other modules or by the main application (e.g., Httpd_Server). The underscore after the module prefix indicates that the procedure is public.

This section does not detail the ncgi and html packages, which are quite useful to the TclHttpd programmer. There are doc files that come with tcllib, and you can find man pages for the tcllib packages in the www.tcl.tk manual section.

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

Table 18-1. Httpd support procedures

Httpd_Error sock code	Returns a simple error page to the client. The code is a numeric error code such as 404 or 500.
Httpd_ReturnData sock type data	Returns a page with Content-Type type and content data.
Httpd_ReturnFile sock type file	Returns a file with Content-Type type.
Httpd_Redirect newurl sock	Generates a 302 error return with a Location of newurl.
Httpd_SelfUrl url	Expands 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 262

Table 18-2. Url support procedures

Url_DecodeQuery query	Decodes a www-url-encoded query string and returns a name, value list. Depreciated. This is equivalent to ncgi::nvlist, which takes no arguments.
Url_Encode value	Returns value encoded according to the www-url-encoded standard.
Url_PrefxInstall prefix handler ?-thread bool? ?-callback cmd? ?-readpost bool?	Registers handler as the handler for all URLs that begin with prefix. The handler is invoked with two additional arguments: sock, the handle to the client, and suffix, the part of the URL after prefix. Use -thread 1 to have the handler run in a worker thread. Use -callback cmd to register a callback invoked at the very end of URL processing. Use -readpost 0 to disable pre-reading post data.

The Doc module procedures for configuration are listed in Table 18-3.

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 directory	Maps the file system directory into the URL subtree starting at virtual.
Doc_ErrorPage file	Specifies 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 how	If how is 1, then .html files are compared against corresponding .tml files and regenerated, if necessary.
Doc_IndexFile pattern	Registers a file name pattern that will be searched for the default index file in directories.
Doc_NotFoundPage file	Specifies 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 dirname	Defines the directory used for each user's home directory. When a URL such as ~user is specified, the dirname under their home directory is accessed.
Doc_TemplateLibrary directory	Adds directory to the auto_path so that the source files in it are available to the server.
Doc_TemplateInterp interp	Specifies an alternate interpreter in which to process document templates (i.e., .tml files.)
Doc_Webmaster ?email?	Sets or queries the email for the Webmaster.

The Doc module procedures for generating results are listed in Table 18-4

Table 18-4. Doc procedures for generating responses

Doc_Error sock errorInfo	Generates 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 sock	Generates 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 name	Returns the cookie name passed to the server for this request, or the empty string if it is not present.
Doc_Dynamic	Turns off caching of the HTML result. Meant to be called from inside a page template.
Doc_IsLinkToSelf url	Returns 1 if the url is a link to the current page.
Doc_Redirect newurl	Raises 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 date	Sets 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 shows the initial elements of the page array that are defined during the processing of a template.

Table 18-6. Elements of the page array

query	The decoded query data in a name, value list. Also available through ncgi.
dynamic	If 1, the results of processing the template are not cached in the corresponding .html file.
filename	The file system pathname of the requested file (e.g., /usr/local/htdocs/tclhttpd/index.html).
template	The file system pathname of the template file (e.g., /usr/local/htdocs/tclhttpd/index.tml).
url	The part of the URL after the server name (e.g., /tclhttpd/index.tml).
root	A relative path from the template file back to the root of the URL tree.

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

Table 18-7. Elements of the env array

AUTH_TYPE	Authentication protocol (e.g., Basic).
CONTENT_LENGTH	The size of the query data.
CONTENT_TYPE	The type of the query data.
DOCUMENT_ROOT	File system pathname of the document root.
GATEWAY_INTERFACE	Protocol version, which is CGI/1.1.
HTTP_ACCEPT	The Accept headers from the request.
HTTP_AUTHORIZATION	The Authorization challenge from the request.
HTTP_COOKIE	The cookie from the request.
HTTP_FROM	The From: header of the request.
HTTP_REFERER	The Referer indicates the previous page.
HTTP_USER_AGENT	An ID string for the Web browser.
PATH_INFO	Extra path information after the template file.
PATH_TRANSLATED	The extra path information appended to the document root.
QUERY_STRING	The form query data.
REMOTE_ADDR	The client's IP address.
REMOTE_USER	The remote user name specified by Basic authentication.
REQUEST_METHOD	GET, POST, or HEAD.
REQUEST_URI	The complete URL that was requested.
SCRIPT_NAME	The name of the current file relative to the document root.
SERVER_NAME	The server name, e.g., www.beedub.com.
SERVER_PORT	The server's port, e.g., 80.
SERVER_PROTOCOL	The protocol (e.g., http or https).
SERVER_SOFTWARE	A software version string for the server.