Wafe and W3C's Libwww

Required Functionality

Several protocols (HTTP, FTP, NNTP and others) accessible through a common programmatic interface.
Additional features, such as caching, logging, or proxy-handling.
Asynchronous transfer for use in a GUI-environment.
High degree of customizability.
Extensibility in order to add new protocols (especially HTTP over SSL).

W3C Reference Library Architecture

Access Manager
Main entry-point for applications, provides high-level functions for downloading/uploading an entity.
Protocol Manager
Coordinates network access for application level protocols and allows registration of new protocols.
Event Manager
Triggers protocol modules if data can be read or written. Cineast uses the X-Toolkit's event handling mechanism.
Error Manager
Collects errors and warnings during transfer for later processing.
Format Manager
Takes care of any conversions of the incoming or outgoing data. Handles content-encodings, character-set conversions and final presentation of a downloaded object using previously defined presenters.

A typical application's structure with Wafe and W3

Wafe's libwww module can be depicted as a state machine in terms of an issued request.
Main states and callback hooks (sideway pointing arrows) are shown in figure above.
As for GUI components, callbacks are specified as Tcl commands.

Network operations with requests and anchors

Anchors
- Libwww's internal representation of an URL and any information on the target object.
- For a download operation usually empty at beginning and filled with data during download.
- For an upload operation usually filled with document metainformation before upload.
- Wafe interface allows creation of an anchor, association with an URL and retrieval of values of attributes.
Requests
- Libwww's internal representation of a networking operation.
- Has many parameters, which configure the networking operation in great detail.
- Wafe interface allows creation of request and modification of attributes.

Example: Simple Download

The following example performs a simple download:

#!/usr/bin/X11/mofe --f





w3LoadAnchor [w3GetAnchor http://mohegan.wi-inf.uni-essen.de/] \


             [w3RequestNew wwwPresent {Presenter {xedit %s}}]

w3GetAnchor creates an empty anchor structure, binds it to a URL and returns a handle for the anchor.
w3RequestNew creates a new request object, configures the destination for incoming data with the wwwPresent attribute and returns a handle for the request.
The request is started and the two handles are passed.
The specified handler dumps downloaded data to a temporary file and executes the xedit editor afterwards. In this case, incremental download is performed but not used.

Example: Incremental Download

This example transfers a large file and prints information including number of bytes read so far every time a new chunk of data arrives:

#!/usr/bin/X11/mofe --f





w3AddConverter image/gif \


             {FileWriter {puts "%r: [w3RequestGet %r bytesRead] Bytes to %d"}}


w3LoadAnchor [w3GetAnchor http://wwwi.wu-wien.ac.at/buchcover.gif] \


             [w3RequestNew postCb {puts Done}]

With w3AddConverter an incremental presenter is registered for a specific content-type.
The incremental presenter used above (FileWriter) appends data to a temporary file and invokes a handler procedure every time new data arrives.
Within the handler procedure, percent-code substitution is used to retrieve the request handle and the filename.
A new request is created using w3RequestNew and a termination handler postCb is registered.
The request is started with w3LoadAnchor using the two handles.

Example: Secure HTTP (SHTTP, HTTP over SSL)

The following example demonstrates, how to access SHTTP in Wafe.

#!/usr/bin/X11/mofe --f





set W3SSL $env(HOME)/.cineast/ssl


set req [w3RequestNew \ 


         wwwPresent     {Presenter {xedit %s}} \ 


         sslPrivateKey  $W3SSL/priv/seen.pem \ 


         sslCertFile    $W3SSL/priv/seen.pem \


         sslVerifyDir   $W3SSL/certs/ \


         sslVerify      peer]


w3LoadAnchor [w3GetAnchor https://www.eunet.co.at/] $req

SSL-parameters can be set as additional request attributes (see example) or as global defaults.
sslPrivateKey and sslCertFile specify the user's credentials for the SSL handshake.
sslVerifyDir specifies the place where certificates of trusted certificate authorities can be found.


prev	index	next