--- name: "mailheaders" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/mailheaders" --- # mailheaders(3bobcat) Handles SMTP Mail Headers ## NAME FBB::MailHeaders - Handles SMTP Mail Headers ## SYNOPSIS **#include \**\ 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 dereferenced 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 move constructor and move assignment operator is available. ## OVERLOADED OPERATORS - o **std::string const &operator\[\](size\_t idx) const**:\ Returns the *idx*-th header line ## 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\::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 ## 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 (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(cout, "\n")); ``` ## FILES *bobcat/mailheaders* - defines the class interface ## SEE ALSO [**bobcat**(7)](/bobcat/7.md) ## BUGS None Reported. ## BOBCAT PROJECT FILES - o *https://fbb-git.gitlab.io/bobcat/*: gitlab project page; Debian Bobcat project files: - o *libbobcat6*: debian package containing the shared library, changelog and copyright note; - o *libbobcat-dev*: debian package containing the static library, headers, manual pages, and developer info; ## 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**).