ehttpd Humelib [incr Tcl] class

NAME

ehttpd - An [incr Tcl] class for an HTTP server.

SYNOPSIS

package require Humelib
ehttpd server_object [-option_name option_value]*
server_object Disable
server_object Init
server_object ReturnData socket content_type content [code [close]]
server_object UrlHandlerClear cmd
server_object UrlHandlerSet document cmd
server_object UrlHandlerUnSet document [cmd]

INHERITANCE

None

OPTIONS (PUBLIC VARIABLES)

Command-Line Switch: -bufsize Default value: 32768

You can optionally override the amount of buffer memory allocated for each client socket connection.

Command-Line Switch: -httpd_addr Default value: {}

You can optionally specify which network interface should be served either as a TCP/IP hostname or as an IP address. Use this option to specify the desired interface when you have more than one TCP/IP network address, or you want to restrict the serving to your own system by specifying localhost. The default behavior is operating system dependent but usually makes the server visible on the first TCP/IP network interface and on the localhost interface. For some operating systems, the served port is reachable on all network interfaces.

Command-Line Switch: -httpd_default Default value: index.html

The default value for a document to be served if the client URL specifies a directory.

Command-Line Switch: -httpd_port Default value: 80

The value of the socket port to be served. The value 80 is the default for the HTTP protocol. A particular port can be used by only one server at a time. In other words, unique port values need to be assigned to every TCP/IP socket server on a computer system. There is no problem having multiple instances of servers running as long as they serve unique ports. Application software is usually assigned port values greater than 1024 to avoid conflicts with system software. It is recommended that values greater than 5000 be used after examining the /etc/services file or reviewing the output of the netstat command for possible conflicts.

Command-Line Switch: -httpd_root Default value: /usr/local/html84

The root file system directory for the webserver.

Command-Line Switch: -Servername Default value: Hume eDiagnostics/EDA web server

The servername value is one of the items appearing in the HTTP header data.

Command-Line Switch: -maxtime Default value: 600000

The value is a time interval specified in milliseconds. If a client connection is not used for this period, the connection is closed.

Command-Line Switch: -TRACE Default value: 0

This integer value is used as a bitfield to control the evaluation of the -tracecmd option value. The table below shows the bit values as hexadecimal integers, and the corresponding information provided if the bit is set.

0x0001: status messages
0x0100: Received HTTP header data
0x0800: Received HTTP query data
0x1000: Sent HTTP header data
0x8000: Sent HTTP content data

Command-Line Switch: -tracecmd Default value: {}

The software has the capability to execute user-defined code in order to trace the data being exchanged or to receive status information. See the -TRACE option above for a description of the bitfield values that control the tracecmd evaluation. The tracecmd is concatenated with three arguments during evaluation, (1) the name of the array holding state information for the particular client connection (2) the pertinent TRACE bit value, and (3) the data that was read or written or a status message. For served files, the file content is not passed during tracecmd evaluation. Instead, a summary message giving the number of bytes passed is passed if bit value 1 is set.

DESCRIPTION

The ehttpd command creates a new [incr Tcl] object whose name is server_object. As with all [incr Tcl] objects, the above options can be modified at any time using the configure method, and the object can be destroyed using ::itcl::delete object server_object. When first created, the object does not attempt to go online. The Init method is used to go online and begin functioning or resume functioning as an HTTP server. The Disable method can be used to shutdown the server interface. The UrlHandlerSet method is used to register code that is executed to provide the server's response for a particular URL. Your handler code can call the ReturnData method in order to send data of your specified mime type as the content of the requested URL. This mechanism is used by the Hume SEMI Interface A software to implement XML/SOAP messaging.

CLASS METHODS

server_object Disable

Disables communication by closing all client socket connections and closing the server socket. Reclaims the memory being used to manage client connections.

server_object Init

Initates or resumes communication by opening the server socket and accepting clients. The successful return value is the served port. If the call is not successful, for example if another process is already using the port, a Tcl error results.

server_object ReturnData socket content_type content [code [close]]

When the UrlHandler* methods are used, this method is called by handler code to specify the reply data sent to the client in response to his request. The socket value is known by the handler as the (sock) state array element. The content_type argument is any mime content type such as "text/xml; charset=utf-8" or "text/plain". The content argument can be an empty string if there is no content, otherwise it is the reply data sent to the client. The ReturnData method works fine for text. If binary information needs to be sent, the techniques used by the ehttpd software to serve binary image files can be imitated. The optional code argument is the HTTP return code which defaults to the usual 200 success value. The optional close argument can be set to 1 to indicate that the client connection is to be closed after the reply is sent. For example, this argument might be set if the client's request was not proper.

server_object UrlHandlerClear cmd

This method is used to remove any registered handlers having the specified callback code.

server_object UrlHandlerSet document cmd

This method is used to register an external command which is executed to reply to a particular "document" request. The document value does not need to exist as a real file, it just has to be a valid document name. Mapping of %nn character codes and directory references such as /./ or // is handled the same as for real documents. In other words, a handler registered for the document EDA.xml is also used for client requests for equivalent forms such as /EDA.xml or /./EDA.xml. The handler code is evaluated after two arguments are appended, (1) the document name, and (2) the name of the array containing state information for the client connection. The array name is fully namespace qualified; its starts with "::" and can be used without a global or namespace declaration. Within the array, the element (sock) specifies the client socket connection, and the element (postdata) specifies the client query data. See the example in the next section of using the UrlHanderSet method with an [incr Tcl] object.

server_object UrlHandlerUnSet document [cmd]

This method is used to remove a handler that has been registered for a particular document.

EXAMPLE

package require Itcl
package require Humelib
::itcl::class edx {
  variable the_server
  public method httpd_respond {url cache} {
    # $cache is ::ehttp::data$sock
    upvar $cache data
    puts "eda::httpd_respond: $cache"
    if { [info exists data(postdata)] } {
        puts "POST data=$data(postdata)"
        }
    # parse, process data
    # reply 
    set type "text/plain"
    set content "<HTML><HEAD></HEAD><BODY>hello world</BODY></HTML>"
    $the_server ReturnData $data(sock) $type $content
    }
  constructor {} {
     set the_server ::e0
     ehttpd $the_server -httpd_port 8024
     $the_server UrlHandlerSet hello.html [list $this httpd_respond]
     $the_server Init
     }
   destructor {
       ::itcl::delete object $the_server
       }
   }
edx #auto

AUTHOR

Hume Integration Software, www.hume.com

KEYWORDS

HTTP, HTTPD, web server, HTML