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 at a
single element of MailHeaders objects. They are separated from each other
by newline (\n) characters. The last line to join a multi-line header is
not terminated by a newline character.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
std::vector<std::string>
ENUMERATIONS
The following enumerations and enumeration values can be used with the
class FBB::MailHeaders:
enum Mode
This enumeration defines two values:
READ:
When this value is specified at construction time, e-mail is
immediately read by the constructor.
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:
FULL:
Used by the setHeaderIterator() (see below) to indicate that the
headers must exactly match a specified header name.
INITIAL:
Used by the setHeaderIterator() (see below) to indicate that the
initial part of the headers must match the specified header text.
PARTIAL:
Used by the setHeaderIterator() (see below) to indicate that the
headers must contain the specified header text.
CASE_FULL:
Used by the setHeaderIterator() (see below) to indicate that the
headers must exactly match a specified header name. The matching is performed
case insensititvely.
CASE_INITIAL:
Used by the setHeaderIterator() (see below) to indicate that the
initial part of the headers must match the specified header text. The matching
is performed case insensititvely.
CASE_PARTIAL:
Used by the setHeaderIterator() (see below) to indicate that the
headers must contain the specified header text. The matching is performed case
insensititvely.
NESTED TYPES
The class MailHeaders defines the following types:
const_hdr_iterator:
An input iterator iterating over the headers selected by the member
setHeaderIterator() (see below)
const_reverse_hdr_iterator:
An input iterator reversely iterating over the headers selected by the
member setHeaderIterator() (see below)
Objects of these two iterator types point to header lines. Their
derefenced types are std::string const.
CONSTRUCTOR
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 copy constructor is available.
MEMBER FUNCTIONS
All members of std::vector<std::string> are available, as
FBB::MailHeaders inherts from this class.
void read():
Reads the mail-headers from the file passed to the FBB::MailHeaders
object's constructor. An FBB::Errno object is thrown if the mailheaders
were already read or if the file is incomplete (i.e., the (obligatory) blank
line wasn't found).
void setHeaderIterator(std::string 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::Errno
exception. An FBB::Errno exception is also thrown if
setHeaderIterator() is called when no mail headers are available.
const_hdr_iterator beginh() const:
Returns the begin-iterator
corresponding to the first header selected by the
setHeaderIterator() member.
Note that the member function's name ends in h, to
distinguish it from the vector<string>::begin() member.
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.
const_reverse_hdr_iterator rbeginh() const:
Returns the reversed begin-iterator
corresponding to the last header selected by the
setHeaderIterator() member.
Note that the member function's name ends in h, to
distinguish it from the vector<string>::rbegin() member.
const_reverse_hdr_iterator endh() const:
Returns the reversed end-iterator matching rbeginh().
Note that the member function's name ends in h, to
distinguish it from the vector<string>::rend() member.
EXAMPLE
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 (Errno &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"));
FILES
bobcat/mailheaders - defines the class interface
SEE ALSO
bobcat(7)
BUGS
None Reported.
DISTRIBUTION FILES
bobcat_2.02.03-x.dsc: detached signature;
bobcat_2.02.03-x.tar.gz: source archive;
bobcat_2.02.03-x_i386.changes: change log;
libbobcat1_2.02.03-x_*.deb: debian package holding the
libraries;
libbobcat1-dev_2.02.03-x_*.deb: debian package holding the
libraries, headers and manual pages;
http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
COPYRIGHT
This is free software, distributed under the terms of the
GNU General Public License (GPL).