W3A/F – WWW Applets/Filters API

May 30, 1995

W3A/F: Filters

Filters add the capability to handle a new format, by translating it to another, already known format. The browser may even try to daisy chain filters, to arrive at a format it knows. Their signature consists of:

1. One or more pairs of (MIME-like) types.

2. The object file(s) to load.

3. A suffix to add to function names.

Question: Do we need a ‘degradation factor’ to describe to the browser how much information will (typically) be lost in the conversion?

A filter must export the following functions:

• Bool initXXX(char ***from, char ***to, int *nrfromto,
float **qual)

Initialized private variables and returns the list of transformations that the filter can do. Each string in from and to is a MIME type. The qual array must be exactly as long as the from array and contain numbers between 0.0 and 1.0. When the function returns FALSE, the errno variable holds the reason.

• Bool openXXX(const char *from_type, const char *from_params,
const char *to_type, const char *to_params, long id)

The types are things like "text/plain", "image/gif". Returns FALSE in case of an error. See errno for error codes.

• int readXXX(long id, char *buf, size_t bufsiz)

Returns number of (converted) characters read. -1 with an errno of EAGAIN means that no converted characters are available yet and a call to writeXXX is required first. A return value of 0 indicates the end of the data.

• int writeXXX(long id, const char *buf, size_t nchars)

Returns number of characters actually written. A return of -1 indicates an error, 0 indicates that a call to readXXX is required first. To indicate to the filter that the end of the data is reached, call writeXXX with nchars=0.

• Bool closeXXX(long id)

Should be called after the last readXXX returns 0. (For error codes, see

  errno)

The browser must call these routines subject to the same constraints m.m. as for the agents.