Simple guide to writing a server in C

In this document I aim to give a brief overview of how to write a new server, based on the generic code supplied as part of WWW.

When you extract the TAR files, you will get three directories created, called common, linemode, and daemon. The common directory contains files some of which will be used by the daemon. However, the main daemon code lies in the implementation directory under the daemon directory. Here there are three files of note: HTDaemon.c, HTRetrieve.c, and HTRules.c.

HTDaemon.c contains the code to handle the communication connection. It should not prove necessary to edit this file. As part of the code, this module calls a function called HTRetrieve. In the standard implementation, the code for this function is placed in HTRetrieve.c

The HTRetrieve function

This function is called by the main function after it has received a message from a client and partially parsed this message. The three arguments the function receives are:

1) the document reference which the client sent (from the hypertext reference),

2) a plus-separated list of keywords, which is empty except were an index search is required,

3) the socket to which the reply should be sent.

The standard function

The general algorithm for the HTRetrieve function looks like this: int HTRetrieve (char * arg, char * keywords, int socket) { if any keywords write an error message to socket (since this server does not do index searches) return else if compiled with the option supplied attempt to transform the UDI in arg by the rules supplied in the rules file endif attempt to open and read the file addressed by arg if able to open the file check the file format if it is in plain text send the <PLAINTEXT> tag to the socket else if it isn't HTML send an error message back that the server can't handle multiple format return endif endif read file and write it to the socket else send error message endif endif } Writing a new server involves either modifying this function in the file HTRetrieve.c, or writing a totally new function in a new file (in which case the make file must be altered to use this one instead. The two most likely changes are either to change the document address format from the standard (UNIX-style) UDI to the local format, or to implement an index server. The former is simply a matter of implementing a function which, given the UDI, will output the address in the local format. The latter is slightly more complicated, and is described below.

Writing an index server

An index server works by taking a plus-separated list of keywords and using it as the basis for querying a database. In most cases it is simple to write a new HTRetrieve function from scratch, of the form: int HTRetrieve (char * arg, char * keywords, int socket) { if (arg != SERVER_NAME) write error message to socket return else if no keywords write back a message explaining what the server is, in HTML, which must include the tag <ISINDEX>, to inform the browser that this is an index else create a query in the langauge of the database, based on the keyword list send this query to the database read the response and convert it to HTML, again including the <ISINDEX> tag write the HTML to the socket endif endif } where SERVER_NAME is the name you are giving to your server, e.g. "ALWHO". Where the response to the query must contain anchors, the HREF entry need only contain the SERVER_NAME and the keywords, not the server internet name and port, e.g. the reference need only be: HREF=/ALWHO?barker not HREF=http://www1.cern.ch:3245/ALWHO?barker It is up to the browser to fill in the missing part.

Making the server

How to create the server executable depends upon the system you are using. For most UNIX platforms it is enough to run the 'make' command in the directory where the daemon sources exist. This will create an executable called 'httpd'.

On the VMS systems, you must type 'mms/macro=(multinet=1)'.

Running the server

To start up the server you must type 'httpd ' possibly followed by one or more command line options. The most important of these is the -a option. This tells the server which port to listen to. For example

httpd -a \*:5000

tells the server to listen to any connection (that's the '*') on port 5000. Note that the backslash is only necessary on UNIX to prevent the * being completed. This command could potentially fail if another process is already using that port. The standard port for WWW servers is port 80, although by default if no -a option is present, the daemon will listen to standard input and write to standard output (the reason for this is given below).

On UNIX systems, the daemon may be run by the inet 'super server' daemon. If this is done, no -a option need by given, since the inet daemon supplied all the data from the port to the WWW server through the standard input and output chanels.

Running multiple servers

If you have a number of different servers on one machine, each providing a different service, e.g. WHO, XFIND, etc, you may wish either to intergrate them all into a single package, or to run each as an independent service.

In the first case you would write the HTRetrieve function with a CASE statement which would decide which database to query depending upon the address supplied in the first argument (arg).

In the second case, each server would have to be run from a different port. Each server is compiled separately, using it's own version of the HTRetrieve function, and then launched with a different port number assigned to it.

______________________________________________________ CTB