W3C libwww LibGuide

W3C Library Interfaces

The W3C Sample Code Library consists of a set of small APIs called interfaces. This section is an overview of all interfaces in the Library. An interface can cover multiple related C modules and it is defined by a WWW*.h include file, for example WWWCore.h. On Windows platforms, each interface corresponds to a DLL with a DLL definition file defining all exported methods and data objects. You can also have a look at the complete list of all public functions.

Every module in the Library has a HTML document associated with it containing a detailed description of the functionality and interface to other modules. This page is the top node for the implementation specific documentation and contains links to all the modules in the Library. The documentation is dynamically kept up to date as the actual include files (.h) are generated from the HTML documents using the Line Mode Browser.

If you are changing any of the interfaces then please note that when compiling make sure that you have a relatively new version of the Line Mode Browser that parses the HTML documents correctly (2.13 and newer versions). Find out what version of the Line Mode Browser you are using by typing

	www -version

Also remember that when editing the module interfaces or adding functionality then always use the HTML files and not the .h files!

Basic Interfaces

The core interfaces must be included in all applications.

Windows Specifics

This is a small interface that handles trace messages on Windows

Basic Utilities

The Utility modules are mostly container modules, dynamic strings and other stuff that you can't live without when building applications. The modules are used by the core part of the W3C Sample Code Library but can also be used by the application. See also the main Library include file called WWWLib.h which contains all converters and protocol modules known to the Library. You can include this one if the application is to use all the functionality of the Library.

Core Interface

This is the basic include file for the core of the W3C Sample Code Library. Together with the WWWUtil module it contains all core specific modules which are required to compile and build the Library. The core part of the Library is designed as a set of registration modules with no real functionality in itself. Instead all the functionality comes when the application registers the modules that provides a desired functionality, for example accessing HTTP servers or the local file system. The Library has a special include file called WWWApp.h which a lot of application helper modules that makes it easier to use the core.

Transport Protocol Interfaces

All transport interfaces are registered dynamically in libwww. This means that libwww is independent of the transport being used (for example TCP) and you can therefore use libwww in any context you like. You have to specify a set of parameters in order for libwww to be able to use it.

Stream Interfaces

Persistent Cache

The cache contains details of temporary disk files which contain the contents of remote documents.

HTML Parser and Generator

This is the include file for the basic HTML module that can be used together with the core of the W3C Sample Code Library. It contains all HTML specific modules which are required to compile and build the HTML DLL. Please note that as the HText is not included in this interface. The reason is that the HText interface only is declared by the Library but must be defined by the application. Therefore it can not be part of a DLL but must be included directly in the application.

Directory Browsing

This is the include file for the directory handling modules that can be used together with the core of the W3C Sample Code Library. It contains all Directory specific modules which are required to compile and build the DIRECTORY DLL.

Special Streams

This interface provides a set of specialized stream. For example a stream for guessing unknown media types from magic words. It also contains streams for downloading a document into a memory buffer, counting content length and much more.

MIME Parser and Generator

This is the module for basic RFC822/MIME parsing that can be used together with the core of the W3C Sample Code Library. It contains all MIME specific modules which are required to compile and build the MIME DLL.

Content Encoding Compression and Decompression Streams

The stream part of the Library is a set of streams that can be used to encode/decode, or compress/decompress content. Many of the streams are based on zlib which is a freely available compression library.

Protocol Interfaces

Local File Access

This is the include file for local file handling modules that can be used together with the core of the W3C Sample Code Library. It contains modules which are required to compile and build the FILE DLL.

FTP Access

This is the include file for the basic FTP module that can be used together with the core of the W3C Sample Code Library. It contains all FTP specific modules which are required to compile and build the FTP DLL.

Gopher Access

This is the include file for the basic GOPHER module that can be used together with the core of the W3C Sample Code Library. It contains all GOPHER specific modules which are required to compile and build the GOPHER DLL.

HTTP Access

This is the include file for all HTTP access including the server side and the client side. It can be used together with the core of the W3C Sample Code Library. It contains all HTTP specific modules which are required to compile and build the HTTP DLL.

News Access

This is the include file for the basic NNTP module that can be used together with the core of the W3C Sample Code Library. It contains all News specific modules which are required to compile and build the News DLL.

Telnet Access

This is the include file for the basic Telnet, rlogin, and TN3270 module that can be used together with the core of the W3C Sample Code Library. It contains all Telnet, rlogin, and TN3270 specific modules which are required to compile and build the Telnet, rlogin, and TN3270 DLL.

WAIS Access

This is the include file for the basic WAIS module that can be used together with the core of the W3C Sample Code Library. It contains all WAIS specific modules which are required to compile and build the WAIS DLL.

Application Interfaces

Application Utilities

A way to initialize applications is to use a rule file, also known as a configuration file. This is for example the case with the W3C httpd and the W3C Line Mode Browser. This module provides basic support for configuration file management and the application can use this is desired. The module is not referred to by the Library. Reading a rule file is implemented as a stream converter so that a rule file can come from anywhere, even across the network!

Applications do not have to provide native support for all protocols, they can in many situations rely on the support of proxies and gateways to help doing the job. Proxy servers are often used to carry client requests through a firewall where they can provide services like corporate caching and other Network Optimizations. Both Proxy servers and gateways can serve as "protocol translators" which can convert a request in the main Web protocol, HTTP, to an equivalent request in another protocol, for example NNTP, FTP, or Gopher. In case a proxy server or a gateway is available to the application, it can therefore by use of HTTP forward all requests to for example a proxy server which then handle the communications with the remote server, for example using FTP about the document and return it to the application (proxy client) using HTTP.

This module provides provides functionality for handling proxies, rule files, and a large set of other application utilities that make it easier to build an application using libwww.

Initialization Modules

The core parts of the Library is a framework for adding functionality. It has hooks for adding protocol modules, like for example HTTP, FTP, and also for adding streams that can convert from one media type to some other type, or presenting the result to the user. In the distribution file of the Library you will find a large set of protocol modules and streams already implemented. However, in order to use these you need to initialize them. This can be done by using the methods in the WWWInit module. You can modify these modules as you like to fit your particular needs. The modules in this interface are not part of any DLL and so must be included directly if desired.


Henrik Frystyk Nielsen, libwww@w3.org,
@(#) $Id: Overview.html,v 1.28 1997/02/18 21:04:30 frystyk Exp $