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().
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:
A bool parameter. The default
value of false specifies that the MIME
document uses the LF character as a newline
sequence. Setting this parameter to true specifies
that the MIME document uses the
CRLF newline character sequence.
This flag gets forwarded to
x::mime::newline_iter's constructor.
A bool parameter that's forwarded to the
section factory processor. The default true
value specifies that this is a traditional context where a MIME
document must have a “Mime-Version: 1.0” header.
A false value specifies a context where MIME
messages rule the roost (like HTTP messages, for
example).
The initial
x::mime::sectioninfo
object that gets passed to the section processor. The default
value gets instantiated by default constructor
(x::mime::sectioninfo::create())
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.