]> W3A -- WWW Applets API, common functions

W3A (common part): Functions exported by the browser

The browser starts applets and feeds them data, but it will also execute tasks on behalf of the applets, such as retrieving a new document and displaying a previous document.

The file w3a.h defines the structs W3ADocumentInfo and W3ABrowserInfo:

typedef struct {
    char *url;
    char *mime_type;
    char *mime_params;
    char *title;
    char *referer;     /* NULL if not known */
    char *status;      /* e.g. "403 not found" */
    char *location;    /* For redirect if status = 3xx */
    long size;         /* in bytes, -1 if unknown */
} W3ADocumentInfo;
 
typedef struct {
    char *version;       /* browser name & version */
    int nformats;        /* # of accepted formats */
    char **formats;      /* accepted formats */
    float *preferences;  /* Each in (0,1] */
} W3ABrowserInfo;
    

When a function changes a field in W3ADocumentInfo, it must free the previous contents and allocate new space on the heap.

The type W3AWindow is defined in the w3a.h file to be the correct type for the platform under which the browser and applets run. Under X it will be an alias for Widget, on other systems it will be something else.

In the following, reference is made to a type Bool and constants FALSE and TRUE. In the w3a.h file, they are defined as macros for int, 0 and 1, respectively.

All browsers that support at least one of W3A/A, W3A/F, W3A/V, W3A/P, and W3A/U, must also provide the following functions:

Question: There are many useful, though not essential functions that many applets share. The browser could offer them, or do we create libWWWutils and simply recommend that authors use it?

Events and synchronization

In some viewers, events can happen that do not immediately cause a new document to be loaded, but that might cause other viewers to do something. For example, two viewers might be synchronized in such a way that a mouse click in one of them causes both windows to display a new image.

Since it not clear at this point what types of events must be supported, W3A only defines an abstract mechanism. The contents and the semantics of events will have to be standardized in some way, or there has to be a way for viewers to agree on events. This is a matter for a future revision.

The current mechanism is very simple: events are identified by a number and may have a single parameter in the form of an untyped pointer. There is no mechanism for filtering events. All events are treated the same and all viewers receive all events.

At the moment, there is only one defined event type, which is used by the browser itself. It has event code 1, and indicates that the browser (successfully) executed a W3Aprocess. Applets that are interested in keeping track of the `current' document, such as hotlist or history applets, can use this. The event-dependent info will be a pointer to a W3ADocumentInfo structure, describing the document that was just opened for viewing. (Note that the browser may send this event more than once for the same document, for example when the document's title changes. Applets must be prepared for this.)

The browser functions as the central event dispatcher. It has a function W3Aevent that an applet calls when it has an event to report. The W3Aevent function then calls every viewer (except the originator of the event) with the same arguments that it received itself.

Every viewer and every user function must have an exported function eventXXX, with four arguments: the applet's ID (long), the ID of the applet in which the event originated (long), the event type (long), and a pointer to event-dependent info (void *). Simple viewers that don't need events must still supply an (empty) function.

Sub-viewers that have been opened by W3AopenView will also be called by the browser. This means that the viewer that opened the sub-viewers does not have to do so itself. But a parent viewer is free to call the eventXXX functions of its sub-viewers if it wants to.

Examples of situations where the event mechanism is usefule are the following:

Error codes

When the above functions fail, they set the errno variable. functions exported by applets should also set this variable when they fail. Apart form the values already defined by the OS libraries, the following four extra values are defined in w3a.h:

EURL

Syntax error in URL

EMETHOD

Illegal method

ENYI

Not yet implemented

ETYPE

No applet for this type

EFORMAT

Error in data

EUSER

Interrupted by user

The interpretation of EUSER depends on the context. It is recommended that an HTML viewer that encounters this error while retrieving in-line images should not retrieve any further images.

Note: Error handling is still a weak spot; something more has to be said about the proper use of errno