Version 3 of httpd.tcl

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

 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.