Provided by: libbobcat-dev_2.20.01-1_amd64 bug

NAME

       FBB::MailHeaders - Handles SMTP Mail Headers

SYNOPSIS

       #include <bobcat/mailheaders>
       Linking option: -lbobcat

DESCRIPTION

       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.

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       -

ENUMERATIONS

       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.

NESTED TYPES

       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 derefenced type is
              std::string.

CONSTRUCTORS

       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 copy and
              move constructors are available.

OVERLOADED OPERATORS

       o      std::string const &operator[](size_t idx) const:
              Returns the idx-th header line The move assignment operator is available

MEMBER FUNCTIONS

       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::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).

       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::Errno exception.  An  FBB::Errno  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

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

       o      bobcat_2.20.01-x.dsc: detached signature;

       o      bobcat_2.20.01-x.tar.gz: source archive;

       o      bobcat_2.20.01-x_i386.changes: change log;

       o      libbobcat1_2.20.01-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_2.20.01-x_*.deb:  debian  package holding the libraries, headers and
              manual pages;

       o      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).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).