W3C Lib Using

Configuration

The architecture of the Library is very flexible and it can be configured for many purposes. It has the advantage that you can set up exactly the configuartion needed for your application but also the disadvantage that it might seeem difficult to use. This section is supposed to describe what you can configure and how it can be done. There are several ways of configuring the Library:

Environment Variables

The Library supports a set of environment variables (or what's equivalent on your platform). Environment variable is a Unix term. On VMS you should use a logical name. These are used to determine the default start up page, what News server to use, whether we should use a Proxy server or a WWW Gateway when requesting a document.

All the environment variables supported by the Library are also supported by the Line Mode Browser, and you can find a list of them under the Customization of the Line Mode Browser

Proxies and Gateways

Applications build on top of the Library can be set up to use a proxy server or a gateway when requesting a document. Using either a proxy server or a gateway enables you efficiently to enhance the functionality of any client without changing the code as all requests between the proxy client and the proxy server (or gateway) are using HTTP only.

The difference between using a proxy server and a gateway is subtle but important: In a gateway request, the DNS part but not the access scheme is sent to the gateway whereas proxy requests include the full URI. As an example, if we are using a WAIS gateway and want to get the following URI:

	wais://quake.think.com?WWW
Then the part sent to a gateway is
	/quake.think.com?WWW
and to a proxy server
	wais://quake.think.com?WWW
Proxy servers have precedence over gateways, so if both a proxy server and a gateway has been defined for an access scheme, then the proxy server is used. You can set up the Library to use either a proxy server or a gateway is done using environment variables as described in Setting up a Proxy Client.

Configuration Flags

Many modules have a global set of variables/flags that can be used to modify the behavior of the modules. There is on general rule that applies to what is configurable, but it is all described in the individual modules, so please look into the declaration files to see what flags exist. An example is how to specify what a directory listing should like.

Static and Dynamic Initialization

The stream manager and the protocol manager are both designed in a highly modular style in that they use pointers to functions when they decide on what protocol or parser to use respectively. For the protocol manager, the actual binding between an access scheme specified in the URI and the protocol module used is done in a separate protocol structure which can be setup at run-time. Likewise for the stream manager where the binding is based on MIME-types, either found directly in the response code from the remote server or by guessing. This model makes it very easy to install new stream converters and protocol modules.
HTInit
The initialisation module for clients. This modules contains functions to setup a list of MIME type converters that the client is capable of handling and a set of bindings between file suffixes and MIME types. The module may be replaced in custom clients.
HTSInit
The initialisation module for servers. May be replaced for custom servers. Not part of the library, but part of the server.
HTRule
The module which reads the configuration file, and does translation of URLs according to rules. It is currently replaced by HTConfig Module in the W3C Server and no rule file is used in the Line Mode Browser in order to keep it simple.

Set up the Stream Interface

Many of the library modules that output data directly to the client or through a server can easily be overwritten, e.g, by a GUI client. Below is a list of moduels that specifically have been propared for this, but other modules can be overwritten as well.

A client can overwrite the graphic object modules in the Library in order to take advantage of a more advanced user-interface. The graphic object has several interfaces, depending on how much of the Library code the client wants to handle on its own (on the figure, the more you are to the left, the more you will have to replace).

SGML Stream Interface
Use this intergace if you do not want to use the SGML parser in the Library and the following transition to a structured stream which is a subclass of the stream class. This can all be set up with out overwriting any module but simply by defining the converters not to use the SGML/HTML parsers.
HTML Structured Stream Interface
If the client has its own HTML parser then the interface is between the client HTML parser and the Library SGML parser. The SGML parser is a general SGML parser which can be setup with a specific DTD and it feeds the HTML parser with structured data. In this case, you will be emulating the HTML module, and generating a hypertext object from the structured stream.
HText Call Back Interface
If the client wants to use the HTML parser in the Library then this is the interface to use for the application. The hypertext object is parsed and the communication with the client is based on a set of call-back functions in the HTML parser. The call-back functions are all defined as prototypes in the HText module but the client must provide the actual code that defines the presentation method used for a specific HTML tag. If you wish to maintain the structure of the SGML file within your object, then the SGML interface will be a better place to connect your code.

Modules to Overwrite

When all public functions and variables within a module are overwritten by module other than the one in the Library, the linker takes the new version and ignores the module in the Library. The following modules are implemented in the Library in order to support the Line Mode Browser but can be overwritten by GUI clients etc.
HTErrorMsg
This module generates and formats the messages on the error stack. If the application wants it own format for the messages, then this module can be overwritten.
HTAlert
See also Description of HTAlert. All communication within the Library to the user goes through this module. It contains functions for prompting for user name etc. Obviously this must be overwritten by GUI clients.
HTHistory
This client module records and replays on request the documents which the user visits. If the application wants a more advanced history management, then this should be overwritten.
HTEvent
This is the internal event loop in the library for multi-threaded protocol access. See also the description of specification of multiple threads. If an application wants its own event loop, then this module must be overwritten.


Henrik Frystyk, libwww@w3.org, November 1995