| 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 code | Returns a simple error page to the client. The code is a numeric error code like 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 249 Table 18-2. Url support procedures.| Url_DecodeQuery query | Decodes a www-url-encoded query string and return a name, value list. | | Url_Encode value | Returns value encoded according to the www-url-encoded standard. | | Url_PrefxInstall prefix callback | Registers 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 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 users home directory. When a URL like ~user is specified, the dirname under their home directory is accessed. | | Doc_TemplateLibrary directory | Adds directory to the auto_path so 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. |
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 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 name | Returns the value of the form value name, or the empty string. | | form::empty name | Returns 1 if the form value name is missing or zero length. | | form::value name | Returns name="name" value="value", where value comes from the query data, if any. | | form::checkvalue name value | Returns 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 value | Returns 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 args | Generates 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.| query | The decoded query data in a name, value list. | | 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.html). | | root | A 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_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. |
|
