Header Fields and how to Extend Them

Libwww provides a few powerful mechanisms to generate and parse header fields for HTTP requests and the like.This section describes how to handle header fields and how to extend the default set of headers. Known headers are the ones that libwww already knows, unknown headers are - guess what - extensions!

Lazy Header Parsing

Regardless of whether a incoming (response) header field are known or not, they are registered in a Response Object but are not parsed until/if they are needed - this is an important performance feature as RFC 822 header fields are hard to parse. If we want to cache the object then the headers are moved to an HTAnchor Object but the headers are still not parsed before we need to.

Generating Known Headers

Libwww manages a known set of headers for which the default behavior it is to use a representative set on each request. However, all known headers can be explicitly enabled or disabled on a per request basis by the application. Here we will mainly describe the set of native headers but leave the description of how to manipulate them for the section on managing Request objects. The native set of headers fall into the following three categories:

General Headers

There are a few header fields which have general applicability for both request and response messages, but which do not apply to the communication parties or the entity being transferred. This mask enables and disables these headers. If the bit is not turned on they are not sent. All headers are optional and the default value is not to use any of these headers at all.

Request Headers

The request header fields allow the client to pass additional information about the request (and about the client itself) to the server. All headers are optional but the default behavior is to use all request headers except From and Pragma. The reason is that the former in general requires permission by the user and the latter has special meanings for proxy servers.

Entity Headers

The entity headers contain information about the object sent in the HTTP transaction. This flag defines which headers are to be sent in a request together with an entity body. All headers are optional but the default value is to use as many as possible.

The set of known headers are equivalent to the set of header defined by the HTTP/1.1 protocol specification. Libwww also provides functionality for registering additional headers which we will have a look at in the next section.

Generating Extension Headers

Each time a request is to be generated, libwww additional headers are to send along with the request. This can happen in three ways as described in the request class

Parsing Headers

The MIME parser stream parses MIME metainformation, for example generated by MIME-like protocols, such as HTTP, and NNTP. For HTTP it handles all headers as defined in HTTP/1.1 of the specification. When a header is parsed, the information is first stored in an HTResponse object.

Parsing Known Headers

The set of headers directly handled by the internal MIME parser is the reader is referred to the actual implementation in order to see the exact list.

Parsing Extension Headers

In many cases, if you have registered an extra set of headers to be generated, you are also in a situation where you would like to handle the result that is returned by the remote server. As we will describe in this section, the Library provides a very similar interface to the one presented above for generating extra headers.

Each time a request is received, and a unknown header is encountered by the internal MIME parser, libwww looks to see if a list of callback functions has been registered to parse additional metainformation. In case a parser is found for this particular header, the call back is called with the header and all parameters that might follow it. As MIME headers can contain line wrappings, the MIME parser canonicalizes the header line before the callback function is called which makes the job easier for the callback function.

Registrering Header Parsers

HTTP Extension Framework

The HTTP extension framework is not yet implement - stay tuned!

Registrering Extensions