FBB::MailHeaders - Handles SMTP Mail Headers
#include <bobcat/mailheaders>
Linking option: -lbobcat
FBB::MailHeaders objects extract header lines from e-mail.
Reading stops at (and including) the first blank line, which becomes the
last element of the FBB::MailHeaders object, interpreted as a
vector. The actual e-mail content is therefore left unread on the
file containing the e-mail.
Each line stored in a MailHeaders object represents a
complete header line. Headers continuing over multiple input lines are
concatenated to a single line retrievable from MailHeaders objects,
separated from each other by ’\n’ (newline) characters.
The last line to join a multi-line header is not terminated by a newline
character.
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
The following enumerations and enumeration values can be used with
the class FBB::MailHeaders:
enum Mode
This enumeration defines two values:
- o
- READ:
When this value is specified at construction time, e-mail is immediately
read by the constructor.
- o
- DONT_READ:
When this value is specified at construction time, e-mail is read using the
read member (see below).
enum Match
This enumeration defines the following values:
- o
- FULL:
Used by setHeaderIterator (see below) to indicate that the headers
must exactly match a specified header name.
- o
- INITIAL:
Used by setHeaderIterator (see below) to indicate that the initial
part of the headers must match the specified header text.
- o
- PARTIAL:
Used by setHeaderIterator (see below) to indicate that the headers
must contain the specified header text.
- o
- CASE_FULL:
Used by setHeaderIterator (see below) to indicate that the headers
must exactly match a specified header name. The matching is performed case
insensititvely.
- o
- CASE_INITIAL:
Used by setHeaderIterator (see below) to indicate that the initial
part of the headers must match the specified header text. The matching is
performed case insensititvely.
- o
- CASE_PARTIAL:
Used by setHeaderIterator (see below) to indicate that the headers
must contain the specified header text. The matching is performed case
insensititvely.
The class MailHeaders defines the following types:
- o
- const_iterator:
An input iterator returned by begin and end (see below)
- o
- const_reverse_iterator:
An reverse input iterator returned by the members rbegin and
rend (see below)
- o
- const_hdr_iterator:
An input iterator returned by the members beginh and endh (see
below)
- o
- const_reverse_hdr_iterator:
An reverse input iterator returned by the members rbeginh and
rendh (see below) Objects of these two iterator types point to
header lines. Their dereferenced type is std::string.
- o
- MailHeaders(std::istream &in, Mode mode = READ):
This constructor defines the file containing the e-mail to be processed. The
second parameter is by default MailHeaders::READ, causing the
object to start reading the e-mail immediately. If set to
MailHeaders::DONT_READ, the e-mail is not read. In that case the
member read can be called to process the e-mail later.
The move constructor and move assignment operator is
available.
- o
- std::string const &operator[](size_t idx) const:
Returns the idx-th header line
- o
- const_iterator begin() const:
Returns an iterator to the first line of the mail headers.
- o
- const_hdr_iterator beginh() const:
Returns the begin-iterator corresponding to the first header selected by the
setHeaderIterator member.
- o
- const_iterator end() const:
Returns an iterator beyond the last line of the mail headers.
- o
- const_hdr_iterator endh() const:
Returns the end-iterator matching beginh. Note that the member
function’s name ends in h, to distinguish it from the
vector<string>::end member.
- o
- const_reverse_iterator rbegin() const:
Returns an iterator to the last line of the mail headers.
- o
- const_reverse_hdr_iterator rbeginh() const:
Returns the reversed begin-iterator corresponding to the last header
selected by the setHeaderIterator member.
- o
- void read():
Reads the mail-headers from the file passed to the FBB::MailHeaders
object’s constructor. An FBB::Exception object is thrown if
the mailheaders were already read or if the file is incomplete (i.e., the
(obligatory) blank line wasn’t found).
- o
- const_iterator rend() const:
Returns an iterator before the first line of the mail headers.
- o
- const_reverse_hdr_iterator rendh() const:
Returns the reversed end-iterator matching rbeginh.
- o
- void setHeaderIterator(char const *header, Match match = FULL):
Sets the header-iterators to the specified header. The parameter
match defines the match-type to use when selecting headers. The
default FBB::MailHeaders::FULL, indicates that the text provided in
header must match exactly an e-mail header.
When matching headers the colon terminating the header is not
considered and should therefore not be specified by
setHeaderIterator.
Alternative matching strategies are used when other values of the
enumeration FBB::Match are specified.
The member setHeaderIterator must have been called at least
once or the members beginh and rendh will throw an
FBB::Exception exception. An FBB::Exception exception is
also thrown if setHeaderIterator is called when no mail headers are
available.
- o
- size_t size() const:
Returns the number of header lines
The following example shows the normal use of these members:
// create a MailHeader object
MailHeaders mh(cin, MailHeaders::DONT_READ);
try
{ // read the headers
mh.read();
}
catch (Exception &err)
{
cout << err.what() << endl;
}
cout << "There are " << mh.size() << " header lines\n";
// look for the Received: headers
mh.setHeaderIterator("Received");
// show the Received headers
copy(mh.beginh(), mh.endh(),
ostream_iterator<std::string const>(cout, "\n"));
bobcat/mailheaders - defines the class interface
- o
- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- o
- bobcat_5.07.00-x.dsc: detached signature;
- o
- bobcat_5.07.00-x.tar.gz: source archive;
- o
- bobcat_5.07.00-x_i386.changes: change log;
- o
- libbobcat1_5.07.00-x_*.deb: debian package containing the
libraries;
- o
- libbobcat1-dev_5.07.00-x_*.deb: debian package containing the
libraries, headers and manual pages;
Bobcat is an acronym of `Brokken’s Own Base Classes And
Templates’.
This is free software, distributed under the terms of the GNU
General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).