mail::Attachment — Create MIME content.
        #include <libmail/attachments.H>
The mail::Attachment class formats a wide variety of MIME messages from raw content. Most of the functionality in this class is provided by the constructors. mail::Attachment provides a variety of constructors for creating content MIME entities, and multipart MIME entities.
| mail::Attachment( | std::string headers, | 
| int content_fd ); | 
| mail::Attachment( | std::string headers, | 
| int content_fd, | |
| std::string charset, | |
| std::string transfer_encoding="" ); | 
| mail::Attachment( | std::string headers, | 
| std::string content_str ); | 
| mail::Attachment( | std::string headers, | 
| std::string content_str, | |
| std::string charset, | |
| std::string transfer_encoding="" ); | 
A non-multipart entity is created by providing the
        content in a file descriptor (content_fd) or explicitly
        (content_str).
The mail::Attachment object makes an internal copy of the file descriptor. The original file descriptor does not need to remain open after the mail::Attachment object is constructed. The duplicate file descriptor will be closed automatically when the object is destroyed.
The headers of the MIME entity are provided explicitly.
        The first argument to the constructor (headers) is usually an
        initialized mail::Header::list(3x)
        object. It's std::string
        operator will conveniently generate a well-formed list of
        mail headers.
The charset and
        transfer_encoding
        parameters are optional. content_fd or content_str provides the raw,
        unencoded, data for the MIME object. The mail::Attachment object will
        heuristically select the most appropriate MIME encoding if
        the charset and
        transfer_encoding
        parameters are not provided.
The data may be either plain text, or binary data.
        mail::Attachment will
        determine it automatically. The optional charset parameter specifies
        the plain text's character set. If specified, it will be
        factored into mail::Attachment's heuristic selection
        of the most appropriate MIME encoding for this plain text
        content. Finally, specifying transfer_encoding will
        override mail::Attachment's
        heuristics, and forcibly set the MIME encoding
        accordingly.
To specify the MIME encoding only, specify an empty
          string for charset (this would be
          appropriate for setting the MIME encoding - which will
          obviously be base64 here -
          for binary content that is not associated with any
          character set.
headers must
        include the Content-Type
        header, but must not contain the Content-Transfer-Encoding header, which
        will be provided by the mail::Attachment class.
It is possible to set content_fd or content_str to something
        that's already MIME-formatted. mail::Attachment will conclude that the
        content is already MIME-formatted when headers already contain a
        Content-Transfer-Encoding
        header, or a Content-Type
        header that sets the MIME type to either “message/rfc822” or any
        “multipart” MIME type.
This is often used when the content is an existing,
        well-formed MIME message. Providing a “Content-Type:
        message/rfc822” in headers creates an attached
        MIME message. This is just one of the two ways to create an
        attached MIME message. A better way to create an attached
        MIME message is described later.
A “multipart” Content-Type header must have a
          “boundary” parameter that
          actually matches the the MIME boundary delimiter in the
          specified content.
A multipart MIME content is constructed by creating mail::Attachment for each content MIME section, then using the following multipart constructors:
| mail::Attachment( | std::string headers, | 
| const
              std::vector<mail::Attachment *>
              &parts ); | 
| mail::Attachment( | std::string headers, | 
| const std::vector<mail::Attachment *> &parts, | |
| std::string multipart_type, | |
| const
              mail::mimestruct::parameterList &multipart_parameters ); | 
The headers of a multipart MIME section must include a
        well-formed Content-Type
        header set to either “message/rfc822”
        or “multipart/subtype”.
        Alternatively, mail::Attachment will supply a
        Content-Type header when
        provided with multipart_type and multipart_parameters.
parts must be
          a vector of exactly one element when multipart_type (or an
          existing Content-Type
          header) is “message/rfc822”).
          mail::Attachment top_attachment;
          std::string buffer;
          bool errflag;
          
             top_attachment->begin();
             while ((buffer=top_attachment->generate(errflag)).size() > 0)
             {
                 std::cout << buffer;
             }
Once all mail::Attachment objects are created,
        the MIME-formatted message is generated by first calling
        the begin() method of the
        topmost mail::Attachment
        object, then repeatedly calling the generate() method until it returns an
        empty string. Each call to generate() returns the next portion of
        the formatted MIME message, and the empty string is
        returned after the entire MIME message is produced. All
        mail::Attachment objects
        must be destroyed immediately afterwards.
A false errflag, when generate() returns an empty string,
        indicates that the MIME-formatted message was generated
        succesfully. A true errflag indicated an
        errno-related failure to
        generate the MIME-formatted message.
generate() will supply
          the “Mime-Version: 1.0” header.
          This header does not need to be explicitly included in
          the headers of
          the topmost mail::Attachment object.