Public interfaces for embedded TclHttpd

# HTTP 1.0 protocol stack, plus connection keep-alive and 1.1 subset.
# This accepts connections and calls out to Url_Dispatch once a request
# has been recieved.  There are several utilities for returning
# different errors, redirects, challenges, files, and data.
#

# Httpd_Init
#
#	Initialize the httpd module.  Call this early.
#
# Side Effects
#	Httpd is a global array containing the global server state
# bufsize:      Chunk size for copies
# fcopy:        True if fcopy is being used.
# initialized:  True after server started.
# ipaddr:       Non-default ipaddr for the server (for multiple interfaces)
# library:      a directory containing the tcl scripts.
# port:         The port this server is serving
# listen:       the main listening socket id
# server:       The server ID for the HTTP protocol.
# shutdown:     A list of Tcl callbacks made when the server shuts down
# sockblock:    blocking mode value for sockets (normally this should be 0)
# timeout1:     Time before the server closes a kept-alive socket (msecs)
# timeout2:     Time before the server kills an in-progress transaction.  (msecs
)
# version:      The version number.
# maxused:      Max number of transactions per socket (keep alive)


# Httpd_Server
#
#	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 Httpd_Init and the init calls for the other modules.
#
# Arguments:
#	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.
#
# Side Effects:
#
#	Creates a listening socket with callback to HttpdAccept.

# Httpd_Shutdown
#
#	Kill the server gracefully
#
# Arguments
#	None
#
# Side Effects:
#
#	Calls the registered shutdown procedures


# Httpd_RegisterShutdown
#
#	Register a Tcl command to be called by Httpd_Shutdown
#
# Arguments
#	cmd	A Tcl command
#
# Side Effects:
#
#	Saves the callback

# Httpd_PostDataSize --
#
# Arguments:
#       sock    Client connection
#
# Results:
#       The amount of post data available.

# Httpd_GetPostData --
#
# Arguments:
#       sock    Client connection
#       varName Name of buffer variable to append post data to
#       size    Amount of data to read this call. -1 to read all available.
#
# Results:
#       The amount of data left to read.  When this goes to zero, you are done.

# Httpd_GetPostChannel --
#
# Arguments:
#       sock            Client connection
#       sizeName        Name of variable to get the amount of post
#                       data expected to be read from the channel
#
# Results:
#       The socket, as long as there is POST data to read

# Httpd_SetCookie
#       Define a cookie to be used in a reply
#       Call this before using Httpd_ReturnFile or
#       Httpd_ReturnData
#
# Arguments:
#       sock    handle on the connection
#       cookie  Set-Cookie line

# Httpd_ReturnFile
#       Return a file.
#
# Arguments:
#       sock    handle on the connection
#       type    is a Content-Type
#       path    is the file pathname
#
# Side Effects:
#       Sends the file contents back as the reply.

# Httpd_ReturnData
#
#	Return data
#
# Arguments
#	type	A Content-Type
#	content	The data to return
#	code 	The HTTP reply code.

# Httpd_ReturnCacheableData
#
#	Return data with a modified-time header so proxies cache it.
#
# Arguments
#	type	A Content-Type
#	content	The data to return
#	date	The modified-time as clock seconds.
#	code 	The HTTP reply code.

# Httpd_Error
# 	Send the error message, log it, and close the socket.
#	Note that the Doc module tries to present a more palatable
#	error display page, but falls back to this if necessary.
#
# Arguments
#
#	sock	The client connection
#	code	The error code (404, etc.)
#	detail	Extra information for the body of the error page. Optional.
#
# Side Effects
#	Completes the transaction with an error response.

# Httpd_Redirect
#
#	Generate a redirect reply (code 302)
#
# Arguments:
#	newurl	The value for the Location header
#	sock	Handle on client connection

# Httpd_RequestAth
#
#	Generate the (401) Authorization required reply
#
# Arguments
#	type	usually "Basic"
#	realm	browsers use this to cache credentials
#
# Side Effects
#	Generates a 401 response that contains a www-authenticate challenge

# Httpd_SockClose
#
#	Close down a client connection
#
# Arguments
#	sock	The client connection

