.TH "FBB::MailHeaders" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "SMTP Mail Headers"

.PP 
.SH "NAME"
FBB::MailHeaders \- Handles SMTP Mail Headers
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/mailheaders>\fP
.br 
Linking option: \fI\-lbobcat\fP 
.PP 
.SH "DESCRIPTION"

.PP 
\fBFBB::MailHeaders\fP objects extract header lines from e\-mail\&. Reading
stops at (and including) the first blank line, which becomes the last element
of the \fBFBB::MailHeaders\fP object, interpreted as a \fBvector\fP\&. The actual
e\-mail content is therefore left unread on the file containing the e\-mail\&.
.PP 
Each line stored in a \fBMailHeaders\fP object represents a complete header
line\&. Headers continuing over multiple input lines are concatenated to a
single line retrievable from \fBMailHeaders\fP objects, separated from each
other by \fI\(cq\&\en\(cq\&\fP (newline) characters\&. The last line to join a multi\-line
header is not terminated by a newline character\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\-
.PP 
.SH "ENUMERATIONS"
The following enumerations and enumeration values can be used with the
class \fBFBB::MailHeaders\fP:
.PP 
\fBenum Mode\fP
.br 
This enumeration defines two values:
.IP o 
\fBREAD\fP:
.br 
When this value is specified at construction time, e\-mail is
immediately read by the constructor\&.
.IP o 
\fBDONT_READ\fP:
.br 
When this value is specified at construction time, e\-mail is read
using the \fIread\fP member (see below)\&.

.PP 
\fBenum Match\fP
.br 
This enumeration defines the following values:
.IP o 
\fBFULL\fP:
.br 
Used by  \fIsetHeaderIterator\fP (see below) to indicate that the
headers must exactly match a specified header name\&.
.IP o 
\fBINITIAL\fP:
.br 
Used by  \fIsetHeaderIterator\fP (see below) to indicate that the
initial part of the headers must match the specified header text\&.
.IP o 
\fBPARTIAL\fP:
.br 
Used by  \fIsetHeaderIterator\fP (see below) to indicate that the 
headers must contain the specified header text\&.
.IP o 
\fBCASE_FULL\fP:
.br 
Used by \fIsetHeaderIterator\fP (see below) to indicate that the
headers must exactly match a specified header name\&. The matching is performed
case insensititvely\&.
.IP o 
\fBCASE_INITIAL\fP:
.br 
Used by \fIsetHeaderIterator\fP (see below) to indicate that the
initial part of the headers must match the specified header text\&. The matching
is performed case insensititvely\&.
.IP o 
\fBCASE_PARTIAL\fP:
.br 
Used by \fIsetHeaderIterator\fP (see below) to indicate that the
headers must contain the specified header text\&. The matching is performed case
insensititvely\&.

.PP 
.SH "NESTED TYPES"

.PP 
The class \fIMailHeaders\fP defines the following types:
.IP o 
\fBconst_iterator\fP:
.br 
An input iterator returned by \fIbegin\fP and \fIend\fP (see
below)
.IP o 
\fBconst_reverse_iterator\fP:
.br 
An reverse input iterator returned by the members \fIrbegin\fP and
\fIrend\fP (see below)
.IP o 
\fBconst_hdr_iterator\fP:
.br 
An input iterator returned by the members \fIbeginh\fP and \fIendh\fP (see
below)
.IP o 
\fBconst_reverse_hdr_iterator\fP:
.br 
An reverse input iterator returned by the members \fIrbeginh\fP and
\fIrendh\fP (see below)
Objects of these two iterator types point to header lines\&. Their
dereferenced type is \fIstd::string\fP\&.
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBMailHeaders(std::istream &in, Mode mode = READ)\fP:
.br 
This constructor defines the file containing the e\-mail to be
processed\&. The second parameter is by default \fBMailHeaders::READ\fP, causing
the object to start reading the e\-mail immediately\&. If set to
\fBMailHeaders::DONT_READ\fP, the e\-mail is not read\&. In that case the member
\fIread\fP can be called to process the e\-mail later\&.

.PP 
The move constructor and move assignment operator is available\&.
.PP 
.SH "OVERLOADED OPERATORS"

.PP 
.IP o 
\fBstd::string const &operator[](size_t idx) const\fP:
.br 
Returns the \fIidx\fP\-th header line

.PP 
.SH "MEMBER FUNCTIONS"

.PP 
.IP o 
\fBconst_iterator begin() const\fP:
.br 
Returns an iterator to the first line of the mail headers\&.
.IP 
.IP o 
\fBconst_hdr_iterator beginh() const\fP:
.br 
Returns the begin\-iterator corresponding to the first header selected by
the \fIsetHeaderIterator\fP member\&. 
.IP 
.IP o 
\fBconst_iterator end() const\fP:
.br 
Returns an iterator beyond the last line of the mail headers\&.
.IP 
.IP o 
\fBconst_hdr_iterator endh() const\fP:
.br 
Returns the end\-iterator matching \fIbeginh\fP\&.  Note that the member
function\(cq\&s name ends in \fIh\fP, to distinguish it from the
\fIvector<string>::end\fP member\&.
.IP 
.IP o 
\fBconst_reverse_iterator rbegin() const\fP:
.br 
Returns an iterator to the last line of the mail headers\&.
.IP 
.IP o 
\fBconst_reverse_hdr_iterator rbeginh() const\fP:
.br 
Returns the reversed begin\-iterator corresponding to the last header
selected by the \fIsetHeaderIterator\fP member\&.  
.IP 
.IP o 
\fBvoid read()\fP:
.br 
Reads the mail\-headers from the file passed to the \fBFBB::MailHeaders\fP
object\(cq\&s constructor\&. An \fBFBB::Exception\fP object is thrown if the mailheaders
were already read or if the file is incomplete (i\&.e\&., the (obligatory) blank
line wasn\(cq\&t found)\&.
.IP 
.IP o 
\fBconst_iterator rend() const\fP:
.br 
Returns an iterator before the first line of the mail headers\&.
.IP 
.IP o 
\fBconst_reverse_hdr_iterator rendh() const\fP:
.br 
Returns the reversed end\-iterator matching \fIrbeginh\fP\&. 
.IP 
.IP o 
\fBvoid setHeaderIterator(char const *header, Match match = FULL)\fP:
.br 
Sets the header\-iterators to the specified \fIheader\fP\&. The parameter
\fImatch\fP defines the match\-type to use when selecting headers\&. The default
\fBFBB::MailHeaders::FULL\fP, indicates that the text provided in
\fIheader\fP must match exactly an e\-mail header\&. 
.br 
When matching headers the
colon terminating the header is \fInot\fP considered and should therefore
\fInot\fP be specified by \fIsetHeaderIterator\fP\&. 
.br 
Alternative matching strategies are used when other values of 
the enumeration \fBFBB::Match\fP are specified\&.
.br 
The member \fIsetHeaderIterator\fP \fImust\fP have been called at least once
or the members \fIbeginh\fP and \fIrendh\fP will throw an \fBFBB::Exception\fP
exception\&. An \fBFBB::Exception\fP exception is also thrown if
\fIsetHeaderIterator\fP is called when no mail headers are available\&.
.IP 
.IP o 
\fBsize_t size() const\fP:
.br 
Returns the number of header lines

.PP 
.SH "EXAMPLE"
The following example shows the normal use of these members:
.nf 

                // create a MailHeader object
    MailHeaders mh(cin, MailHeaders::DONT_READ);

    try
    {           // read the headers
        mh\&.read();
    }
    catch (Exception &err)
    {
        cout << err\&.what() << endl;
    }

    cout << \(dq\&There are \(dq\& << mh\&.size() << \(dq\& header lines\en\(dq\&;

                // look for the Received: headers    
    mh\&.setHeaderIterator(\(dq\&Received\(dq\&);

                // show the Received headers
    copy(mh\&.beginh(), mh\&.endh(), 
            ostream_iterator<std::string const>(cout, \(dq\&\en\(dq\&));
    
.fi 

.PP 
.SH "FILES"
\fIbobcat/mailheaders\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP