Chapter 63. Processing structured headers

#include <x/headersimpl.H>
#include <x/mime/structured_content_header.H>

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

x::mime::structured_content_header
    content_disposition("attachment; x-source=file; filename=\"filename.txt\"");

if (content_disposition == "attachment")
{
    ...
}

// ...

std::string name;
std::string filename;

x::mime::structured_content_header content_disposition("attachment")
    ("x-source", "file")
    .rfc2047("name", name, "UTF-8")
    .rfc2231("filename", filename, "UTF-8");

// ...

x::mime::parameters_t::iterator b=content_disposition.parameters.begin(),
    e=content_disposition.parameters.begin();

while (b != e)
{
    std::string name=b->first;

    x::mime::parameter_t parameter=b->second;

    std::string value=parameter.value;

    // ...
}

// ...

content_disposition
    .append(headers, x::mime::structured_content_header::content_disposition);

x::mime::structured_content_header represents a structured MIME header, like Content-Type or Content-Disposition. It consists of a value member, giving the primary value of the header, with the header parameters kept in a parameters_t parameters member, which is a case-insensitive keyed std::multimap.

x::mime::structured_content_header's non-default constructor takes the entire value of the header, or just its primary value, and breaks it down into the value and the parameters. Alternatively, various methods construct build the header, piece by piece, using operator() and rfc2231() methods. They return a x::mime::structured_content_header & for convenience.

operator() adds a simple, unformatted parameter, by name and value. rfc2047() encodes a parameter that may potentially have non-Latin characters, using the method specified in RFC 2047. rfc2231() encodes a parameter that may potentially have non-Latin characters, using the method specified in RFC 2231. Both rfc2047() and rfc2231() take the following additional parameters, in addition to the parameter's name and value:

The value does not get encoded if it does not have to be, in which case the results are the same as with operator(). The value parameter's value gets encoded using the RFC 2047 or 2231 method, if the value contains any characters that require encoding (which includes any non-Latin characters). With rfc2231(), if the value does not have any characters that require encoding, but name=value is near, or exceeds, the targeted line with, it gets encoded as multiple RFC 2231 parameter fragments. Specifying the target line with as 0 results in the parameter getting encoded only if it contains any characters that require it, essentially setting an unlimited maximum targeted line with.

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

x::mime::structured_content_header
    hdr(headers, x::mime::structured_content_header::content_type);

std::string type=hdr.mime_content_type();
std::string subtype=hdr.mime_content_subtype();

if (type == "text")
{
    std::string charset=hdr.charset("iso-8859-1");

    // ...
}

std::string name=hdr.decode_utf8("name", "iso-8859-1");

// ...

hdr.append(headers, x::mime::structured_content_header::content_disposition)

Passing an x::headersimpl as the first parameter to the constructor, and a name of a header for the second parameter, constructs the x::mime::structured_content_header from the value of the header with the given name. The x::mime::structured_content_header gets initialized with an empty string if the x::headersimpl does not have this header.

The x::mime::structured_content_header class includes definitions of some common header names and parameters, like x::mime::structured_content_header::content_type, which is Content-Type.

Additional methods return values of most common parameters. mime_content_type() and mime_content_subtype() gives the MIME content type and subtype. For text types, charset() returns the value of the charset parameter, its argument gives the default return value if the header did not have a charset parameter.

decode_utf8() returns the value of an arbitrary parameter, converted to the UTF-8 character set. decode_utf8() understands character set encoding methods specified in RFC 2047 and RFC 2231. decode_utf8() 's parameter gives the default character set when it is unspecified by the parameter's value, resulting in the conversion of the parameter's value from the given character set to UTF-8.