What follows is detailed interface documentation for the tclhttpd file lib/httpd.tcl, culled from the source, and from wherever it's available. The intention of this is to encourage people to use httpd.tcl's facilities more effectively, to accumulate detailed hints, experiences and examples, and to improve tclhttpd's low-level documentation. [CMcC] 2003-10-08 ---- '''Server Control''' ---- Httpd_Server {port} {name} {ipaddr} port: The TCP listening port number name: The qualified host name returned in the Host field. Defaults to info hostname ipaddr: Non-default interface address. Otherwise IP_ADDR_ANY is used so the server can accept connections from any interface. Start the server by listening for connections on the desired $port. This may be re-run to re-start the server. Call this late, after the init calls for the other modules. ---- Httpd_SecureServer {port} {name} {ipaddr} Like Httpd_Server, but with additional setup for SSL. This requires the TLS extension. ---- Httpd_VirtualHost host file Create a slave interpreter for the named $host and load a complete tclhttpd into it, configured by $file. A request for $host will be handled by the corresponding slave interp. The actual mechanism is that the master interp accepts all socket connections. When the Host: header on the request is received, the connection gets passed to the appropriate slave interp for further handling. If there is no Host: header (really ancient clients?) or if the Host: value is not one of those specified in the Config virtual argument, then the master interp handles the request according to whatever additional configuration details are found in the master configuration file. In a sense, every IP address served by tclhttpd has a "default" site determined by the master config file. The configuration values used in the slave interp are first inherited from the master. In the $configFile, you only need to specify those values that distinguish the virtual site from the default site. In my experience that usually includes the following Config options: docRoot, main, webmaster, and LogFile. ---- Httpd_VirtualHosts hosts file Create virtual hosts for the names in $hosts with the configuration $file ---- Httpd_ServerShutdown Close the server's HTTP socket. ---- Httpd_RegisterShutdown cmd ''called by: counter.tcl'' Register a Tcl command to be called by Httpd_Shutdown ---- Httpd_SecureServerShutdown Close the server's secure socket. ---- Httpd_Shutdown ''called by: srvui.tcl'' Kill the server gracefully ---- '''Server Information''' ---- Httpd_SecurePort The server's secure port. ---- Httpd_Webmaster ''called by: debug.tcl'' return or define an email address for the webmaster ---- '''Connection Information''' ---- Httpd_SelfUrl url sock ''called by: redirect.tcl'' Create an absolute URL for this server ---- Httpd_Protocol sock Return the protocol for the connection ---- Httpd_Port sock Return the port for the connection ---- Httpd_Name sock Return the server name for the connection ---- Httpd_CurrentSocket {sock} Return (or set) the handle to the current socket. ---- Httpd_DumpHeaders sock Dump out the protocol headers so they can be saved for later. ---- Httpd_Peername sock ''called by: logstd.tcl'' The clients dns name. ---- Httpd_RequestComplete sock ''called by: url.tcl'' Detect if a request has been sent. The holder of a socket might need to know of the URL request was completed with one of the return-data commands, or is still lingering open. ---- '''Connection Control''' ---- Httpd_RequestAuth sock type realm ''called by: auth.tcl'' sock: Socket connection type: usually "Basic" realm: browsers use this to cache credentials Generate the (401) Authorization required reply ---- Httpd_Suspend sock {timeout} ''called by: url.tcl'' Suspend Wire Callback - for async transactions Use Httpd_Resume once you are back in business ---- Httpd_Resume sock {timeout} Resume processing of a request. Sets up a bit of global state that has been cleared by Httpd_Suspend. ---- Httpd_SockClose sock closeit {message} ''called by: cgi.tcl url.tcl'' sock: Identifies the client connection closeit: 1 if the socket should close no matter what message: Logging message. If this is "Close", which is the default, then an entry is made to the standard log. Otherwise an entry is made to the debug log. "Close" a connection, although the socket might actually remain open for a keep-alive connection. This means the HTTP transaction is fully complete. ---- Httpd_CompletionCallback sock cmd ''called by: url.tcl'' Register a procedure to be called when an HTTP request is completed, either normally or forcibly closed. This gives a URL implementation a guaranteed callback to clean up or log requests. ---- Httpd_Error sock code {detail} ''called by: auth.tcl cgi.tcl doc_error.tcl include.tcl url.tcl'' send the error message, log it, and close the socket. ---- Httpd_Pair sock fd ''called by: none'' Pair two fd's - typically for tunnelling Close both if either one closes (or gets an error) ---- '''Cookie Commands''' ---- Httpd_SetCookie sock cookie {modify} ''called by: cookie.tcl'' sock: Identifies the client connection cookie: Set-Cookie line modify: (optional) If true, overwrite any preexisting cookie that matches. This way you can change the expiration time. Define a cookie to be used in a reply Call this before using Httpd_ReturnFile or Httpd_ReturnData ---- Httpd_RemoveCookies sock pattern ''called by: interface'' sock: Identifies the client connection pattern: glob pattern to match agains cookies. Remove previously set cookies from the reply. Any cookies that match the glob pattern are removed. This is useful for expiring a cookie that was previously set. ---- '''Connection Reply''' ---- Httpd_ReturnFile sock type path {offset} ''called by: doc.tcl snmp.tcl status.tcl template.tcl'' sock: Identifies the client connection type: is a Content-Type path: is the file pathname offset: (optional) amount to skip at the start of file Return a file. ---- Httpd_ReturnData sock type content {code} {close} ''called by: direct.tcl imagemap.tcl include.tcl snmp.tcl status.tcl template.tcl upload.tcl'' sock: Identifies the client connection type: a Content-Type content: the data to return code: (optional - default 200) the HTTP reply code. close: (optional - default 0) prefer to close the socket Return data for a page. ---- Httpd_ReturnCacheableData sock type content date {code} ''called by: interface'' sock: Identifies the client connection type: a Content-Type content: the data to return date: Modify date of the date code: (optional - default 200) the HTTP reply code. Return data with a Last-Modified time so that proxy servers can cache it. Or they seem to, anyway. ---- Httpd_NotModified sock ''called by: none'' Generate a Not Modified reply (code 304) ---- '''Post Commands''' ---- Httpd_PostDataSize sock ''called by: template.tcl'' The amount of post data available. ---- Httpd_GetPostData sock varName {size} ''called by: thread.tcl url.tcl'' The amount of data left to read. When this goes to zero, you are done. ---- Httpd_GetPostDataAsync sock varName blockSize cmd ''called by: none'' sock: Identifies the client connection varName: Name of buffer variable to append post data to. This must be a global or fully scoped namespace variable, or this can be the empty string, in which case the data is discarded. blockSize: Default read block size. cmd: Callback to make when the post data has been read. It is called like this: cmd $sock $varName $errorString (Where the errorString is only passed if an error occurred.) Read the POST data into a Tcl variable, but do it in the background so the server doesn't block on the socket. This schedules a readable fileevent to read all the POST data asynchronously. The data is appened to the named variable. The callback is made ---- Httpd_ReadPostDataAsync sock cmd ''called by: url.tcl'' Convenience layer on Http-GetPostDataAsync to read the POST data into a the data(query) variable. ---- Httpd_CopyPostData sock channel cmd ''called by: none'' sock: Identifies the client connection channel: Channel, e.g., to a local file or to a proxy socket. cmd: Callback to make when the post data has been read. It is called like this: cmd $sock $varName $errorString (Where the errorString is only passed if an error occurred.) Copy the POST data to a channel and make a callback when that has completed. ---- Httpd_GetPostChannel sock sizeName ''called by: none'' sock: Identifies the client connection sizeName: Name of variable to get the amount of post data expected to be read from the channel The socket, as long as there is POST data to read ---- '''Redirection Commands''' ---- Httpd_Redirect newurl sock ''called by: direct.tcl imagemap.tcl redirect.tcl url.tcl'' Generate a redirect reply (code 302) ---- Httpd_RedirectSelf newurl sock ''called by: redirect.tcl snmp.tcl'' Generate a redirect to another URL on this server. ---- Httpd_RedirectDir sock ''called by: doc.tcl'' Generate a redirect because the trailing slash isn't present on a URL that corresponds to a directory. ----