| You can implement new kinds of domains that provide your own interpretation of a URL. This is the most flexible interface available to extend the web server. You provide a callback that is invoked to handle every request in a domain, or subtree, of the URL hierarchy. The callback interprets the URL, computes the page content, and returns the data using routines from the Httpd module. Example 18-1 defines a simple domain that always returns the same page to every request. The domain is registered with the Url_PrefixInstall command. The arguments to Url_PrefixInstall are the URL prefix and a callback that is called to handle all URLs that match that prefix. In the example, all URLs that have the prefix /simple are dispatched to the SimpleDomain procedure. Example 18-1 A simple URL domain. Url_PrefixInstall /simple [list SimpleDomain /simple] proc SimpleDomain {prefix sock suffix} { upvar #0 Httpd$sock data # Generate page header set html "<title>A simple page</title>\n" append html "<h1>$prefix$suffix</h1>\n" append html "<h1>Date and Time</h1>\n" append html [clock format [clock seconds]] # Display query data if {[info exist data(query)]} { append html "<h1>Query Data</h1>\n" append html "<table>\n" foreach {name value}[Url_DecodeQuery $data(query)] { append html "<tr><td>$name</td>\n" append html "<td>$value</td></tr>\n" } append html "</table>\n" } Httpd_ReturnData $sock text/html $html } The SimpleDomain handler illustrates several properties of domain handlers. The sock and suffix arguments to SimpleDomain are appended by Url_Dispatch when it invokes the domain handler. The suffix parameter is the part of the URL after the prefix. The prefix is passed in as part of the callback definition so the domain handler can recreate the complete URL. For example, if the server receives a request for the URL /simple/page, then the prefix is /simple, the suffix is /request. Connection State and Query Data The sock parameter is a handle on the socket connection to the remote client. This variable is also used to name a state variable that the Httpd module maintains about the connection. The name of the state array is Httpd$sock, and SimpleDomain uses upvar to get a more convenient name for this array (i.e., data): upvar #0 Httpd$sock data An important element of the state array is the query data, data(query). This is the information that comes from HTML forms. The query data arrives in an encoded format, and the Url_DecodeQuery procedure is used to decode the data into a list of names and values. Url_DecodeQuery is similar to Cgi_List from Example 11-5 on page 154 and is a standard function provided by url.tcl. Returning Results Finally, once the page has been computed, the Httpd_ReturnData procedure is used to return the page to the client. This takes care of the HTTP protocol as well as returning the data. There are three related procedures, Httpd_ReturnFile, Httpd_Error, and Httpd_Redirect. These are summarized in Table 18-1 on page 261. | 
