Chapter 34. Headers

x::headersbase is a non reference-counted container for something that looks like a set of HTTP or MIME headers. This class is typically not used directly, but via one of its two subclasses: x::headersimpl<x::headersbase::crlf_endl> or x::headersimpl<x::headersbase::lf_endl>.

x::headersbase provides methods for using headers that were already parsed. The two template-based subclasses provide methods for parsing headers in environments where individual lines of text are terminated by either the CRLF or LF character sequence:

x::headersbase::lf_endl

Each header line is terminated by the LF character.

x::headersbase::crlf_endl

Each header line is terminated by the CRLF character sequence. Lone CR and LF characters are syntactically considered to be a part of the header's contents.

x::headersimpl<x::headersbase::crlf_endl> headers;

headers.parse(std::cin);

This example parses headers from an input stream. The headers may be also parsed from some arbitrary input sequence that's defined by an beginning and ending input iterators:

x::headersimpl<x::headersbase::crlf_endl> headers;

headers.parse(buf.begin(), buf.end());

parse() interprets each line as header: value. A line that begins with a whitespace character is considered to be a continuation of the value from the previous line. The combined, or folded value includes the intervening LF or CRLF.

x::headersbase::iterator and x::headersbase::const_iterator define opaque type that iterate over an associative multimap keyed by headers' names:

x::headersbase::const_iterator p(headers.find("Mime-Version"));

if (p != headers.end())
    std::cout << p->second.value() << std::endl;

x::headers defines a small subset of methods of a std::multimap: begin(), end(), find(), equal_range(), and erase() (several overloaded flavors). Use equal_range() to process headers which may occur more than once.

The multimap's iterators point to a pair whose second value is x::headersbase::header_map_val_t. This class defines three methods:

name()

Returns this header's name.

value()

Returns the value of the header. The leading and trailing whitespace is trimmed off (but any internal LF or CRLF sequences in folded headers are preserved as is).

begin() and end()

Returns a beginning and an ending iterator for a sequence that defines the header's value. This is less expensive than value().

x::headerbase's list() returns a const std::list<x::headerbase::header> & that contains the entire set of headers, in their original order. x::headerbase::header is a subclass of std::string that also implements the same name(), value(), and nameiter() methods that are implemented by x::headersbase::header_map_val_t.

The x::headersimpl template subclass provides additional methods. parse() was described previously. toString() is the opposite of parse(), it formats the headers into an output iterator. append() adds a line of text to the parsed headers. If the line starts with a space, the line is appended to the most recently appended header. replace() removes any existing header and replaces it.

These classes are not reference-counted objects, and must remain in scope as long as any instantiated iterator remains in scope.