Creating MIME entity parsers

The functions described in this section implement high level MIME parsing, by preparing the environment for x::mime::make_entity_parser() using the appropriate context.

These functions employ a section processor factory. This is a functor or a lambda that takes two parameters: a reference to the section information object and a bool flag.

The section processor factory is expected to call x::mime::make_entity_parser(), forwarding the x::mime::sectioninfo to it, without further processing, and the section processor's return value is expected to be the output iterator that's returned by x::mime::make_entity_parser().

Note

After the section processor factory returns, the output iterator iterates over the contents of the MIME section. At the time the factory gets invoked, the x::mime::sectioninfo is a freshly-constructed object, and does not yet reflect the MIME section's actual metrics.

The x::mime::sectioninfo object is complete only after the output iterator finishes iterating over the MIME section, including the trailing eof. The section processor factory can save this x::mime::sectioninfo, which is a reference to a reference-counted object, to be digested at a later time.

The bool flag is true when the section processor factory gets invoked to produce an output iterator for the top level MIME document section, or for the body of a message/rfc822. The section processor factory constructs an output iterator for the header portion of the MIME entity, and invokes x::mime::make_entity_parser(), passing it the header iterator as the first parameter. A true bool indicates whether the header iterator must find the Mime-Version: 1.0 header, before recognizing any other MIME header. Pedantically, in absence of the Mime-Version: 1.0 header, none of the Content headers should be considered as MIME header, and the message content should be treated as a non-MIME text/plain message.

Otherwise, processor can safely assume that it's being invoked on behalf of a subsection of a MIME document that specified the header, and process all Content headers.

x::mime::make_document_entity_parser() constructs an output iterator over chars containing an entire MIME document. x::mime::make_document_entity_parser() constructs an x::mime::newline_iter that invokes the section factory object passed as the first parameter to x::mime::make_document_entity_parser(), that sets up the output iterator over the entire MIME document.

x::mime::make_document_entity_parser() has three optional parameters:

After iterating using the output iterator returned by x::mime::make_document_entity_parser(), its get()->eof() method gets invoked to signal the end of the iteration.

examples/mime/bodydecoder2.C is a modified version of bodydecoder.C that uses x::mime::make_document_entity_parser() instead of manually constructing an x::mime::newline_iter and invoking x::mime::make_entity_parser directly.