<html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/> <title>mail::Attachment</title> <link rel="stylesheet" href="manpage.css" type="text/css"/> <link rel="start" href="index.html" title="Cone: COnsole Newsreader And Emailer"/> <link rel="up" href="misc.html" title="Extra/Miscellaneous objects/methods"/> <link rel="prev" href="address.html" title="mail::address"/> <link rel="next" href="emailaddress.html" title="mail::emailAddress"/> <link xmlns="" rel="icon" href="icon.gif" type="image/gif"/> <meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/> <!-- Copyright 2002 - 2007 Double Precision, Inc. See COPYING for distribution information. --> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center" rowspan="1"> mail::Attachment</th> </tr> <tr> <td width="20%" align="left" rowspan="1" colspan="1"> <a accesskey="p" href="address.html" shape="rect">Prev</a> </td> <th width="60%" align="center" rowspan="1" colspan="1"> Extra/Miscellaneous objects/methods</th> <td width="20%" align="right" rowspan="1" colspan="1">  <a accesskey="n" href="emailaddress.html" shape="rect">Next</a></td> </tr> </table> <hr/> </div> <div class="refentry" lang="en" xml:lang="en"> <a id="mail-attachments" shape="rect" name="mail-attachments"> </a> <div class="titlepage"/> <div class="refnamediv"> <h2>Name</h2> <p>mail::Attachment — Create MIME content.</p> </div> <div class="refsynopsisdiv"> <h2>Synopsis</h2> <div class="literallayout"> <p><br clear="none"/> #include <libmail/attachments.H><br clear="none"/></p> </div> </div> <div class="refsect1" lang="en" xml:lang="en"> <a id="id640172" shape="rect" name="id640172"> </a> <h2>USAGE</h2> <p>The <span class="structname">mail::Attachment</span> class formats a wide variety of MIME messages from raw content. Most of the functionality in this class is provided by the constructors. <span class="structname">mail::Attachment</span> provides a variety of constructors for creating content MIME entities, and multipart MIME entities.</p> <div class="refsect2" lang="en" xml:lang="en"> <a id="id640190" shape="rect" name="id640190"> </a> <h3>Creating content MIME entities</h3> <div class="funcsynopsis"> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td rowspan="1" colspan="1"><code class="funcdef"><b class="fsfunc">mail::Attachment</b>(</code></td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">headers</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">int  </td> <td rowspan="1" colspan="1"><var class="pdparam">content_fd</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td rowspan="1" colspan="1"><code class="funcdef"><b class="fsfunc">mail::Attachment</b>(</code></td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">headers</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">int  </td> <td rowspan="1" colspan="1"><var class="pdparam">content_fd</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">charset</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">transfer_encoding</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td rowspan="1" colspan="1"><code class="funcdef"><b class="fsfunc">mail::Attachment</b>(</code></td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">headers</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">content_str</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> <tr> <td rowspan="1" colspan="1"><code class="funcdef"><b class="fsfunc">mail::Attachment</b>(</code></td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">headers</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">content_str</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">charset</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">transfer_encoding</var><code>)</code>;</td> </tr> </table> </div> <p>A non-multipart entity is created by providing the content in a file descriptor (<em class="parameter"><code>content_fd</code></em>) or explicitly (<em class="parameter"><code>content_str</code></em>).</p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> <p>The <span class="structname">mail::Attachment</span> object makes an internal copy of the file descriptor. The original file descriptor does not need to remain open after the <span class="structname">mail::Attachment</span> object is constructed. The duplicate file descriptor will be closed automatically when the object is destroyed.</p> </div> <p>The headers of the MIME entity are provided explicitly. The first argument to the constructor (<em class="parameter"><code>headers</code></em>) is usually an initialized <a class="link" href="header-list.html" title="mail::Header::list" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::Header::list</span>(3x)</span></a> object. It's <code class="function">std::string</code> operator will conveniently generate a well-formed list of mail headers.</p> <p>The <em class="parameter"><code>charset</code></em> and <em class="parameter"><code>transfer_encoding</code></em> parameters are optional. <em class="parameter"><code>content_fd</code></em> or <em class="parameter"><code>content_str</code></em> provides the raw, unencoded, data for the MIME object. The <span class="structname">mail::Attachment</span> object will heuristically select the most appropriate MIME encoding if the <em class="parameter"><code>charset</code></em> and <em class="parameter"><code>transfer_encoding</code></em> parameters are not provided.</p> <p>The data may be either plain text, or binary data. <span class="structname">mail::Attachment</span> will determine it automatically. The optional <em class="parameter"><code>charset</code></em> parameter specifies the plain text's character set. If specified, it will be factored into <span class="structname">mail::Attachment</span>'s heuristic selection of the most appropriate MIME encoding for this plain text content. Finally, specifying <em class="parameter"><code>transfer_encoding</code></em> will override <span class="structname">mail::Attachment</span>'s heuristics, and forcibly set the MIME encoding accordingly.</p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> <p>To specify the MIME encoding only, specify an empty string for <em class="parameter"><code>charset</code></em> (this would be appropriate for setting the MIME encoding - which will obviously be <code class="literal">base64</code> here - for binary content that is not associated with any character set.</p> </div> <p><em class="parameter"><code>headers</code></em> must include the <code class="literal">Content-Type</code> header, but must not contain the <code class="literal">Content-Transfer-Encoding</code> header, which will be provided by the <span class="structname">mail::Attachment</span> class.</p> </div> <div class="refsect2" lang="en" xml:lang="en"> <a id="id640520" shape="rect" name="id640520"> </a> <h3>Pre-formatted MIME content</h3> <p>It is possible to set <em class="parameter"><code>content_fd</code></em> or <em class="parameter"><code>content_str</code></em> to something that's already MIME-formatted. <span class="structname">mail::Attachment</span> will conclude that the content is already MIME-formatted when <em class="parameter"><code>headers</code></em> already contain a <code class="literal">Content-Transfer-Encoding</code> header, or a <code class="literal">Content-Type</code> header that sets the MIME type to either “<span class="quote">message/rfc822</span>” or any “<span class="quote">multipart</span>” MIME type.</p> <p>This is often used when the content is an existing, well-formed MIME message. Providing a “<span class="quote">Content-Type: message/rfc822</span>” in <em class="parameter"><code>headers</code></em> 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.</p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> <p>A “<span class="quote">multipart</span>” <code class="literal">Content-Type</code> header must have a “<span class="quote">boundary</span>” parameter that actually matches the the MIME boundary delimiter in the specified content.</p> </div> </div> <div class="refsect2" lang="en" xml:lang="en"> <a id="id640608" shape="rect" name="id640608"> </a> <h3>Creating multipart MIME content</h3> <p>A multipart MIME content is constructed by creating <span class="structname">mail::Attachment</span> for each content MIME section, then using the following multipart constructors:</p> <div class="funcsynopsis"> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td rowspan="1" colspan="1"><code class="funcdef"><b class="fsfunc">mail::Attachment</b>(</code></td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">headers</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">const std::vector<mail::Attachment *> & </td> <td rowspan="1" colspan="1"><var class="pdparam">parts</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> <tr> <td rowspan="1" colspan="1"><code class="funcdef"><b class="fsfunc">mail::Attachment</b>(</code></td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">headers</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">const std::vector<mail::Attachment *> & </td> <td rowspan="1" colspan="1"><var class="pdparam">parts</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">std::string  </td> <td rowspan="1" colspan="1"><var class="pdparam">multipart_type</var>,</td> </tr> <tr> <td rowspan="1" colspan="1"> </td> <td rowspan="1" colspan="1">const mail::mimestruct::parameterList & </td> <td rowspan="1" colspan="1"><var class="pdparam">multipart_parameters</var><code>)</code>;</td> </tr> </table> </div> <p>The headers of a multipart MIME section must include a well-formed <code class="literal">Content-Type</code> header set to either “<span class="quote">message/rfc822</span>” or “<span class="quote">multipart/<em class="replaceable"><code>subtype</code></em></span>”. Alternatively, <span class="structname">mail::Attachment</span> will supply a <code class="literal">Content-Type</code> header when provided with <em class="parameter"><code>multipart_type</code></em> and <em class="parameter"><code>multipart_parameters</code></em>.</p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> <p><em class="parameter"><code>parts</code></em> must be a vector of exactly one element when <em class="parameter"><code>multipart_type</code></em> (or an existing <code class="literal">Content-Type</code> header) is “<span class="quote">message/rfc822</span>”).</p> </div> </div> <div class="refsect2" lang="en" xml:lang="en"> <a id="id640766" shape="rect" name="id640766"> </a> <h3>Generating MIME-formatted messages</h3> <div class="literallayout"> <p><br clear="none"/> mail::Attachment top_attachment;<br clear="none"/> std::string buffer;<br clear="none"/> bool errflag;<br clear="none"/> <br clear="none"/>    top_attachment->begin();<br clear="none"/>    while ((buffer=top_attachment->generate(errflag)).size() > 0)<br clear="none"/>    {<br clear="none"/>        std::cout << buffer;<br clear="none"/>    }<br clear="none"/></p> </div> <p>Once all <span class="structname">mail::Attachment</span> objects are created, the MIME-formatted message is generated by first calling the <code class="function">begin</code>() method of the topmost <span class="structname">mail::Attachment</span> object, then repeatedly calling the <code class="function">generate</code>() method until it returns an empty string. Each call to <code class="function">generate</code>() returns the next portion of the formatted MIME message, and the empty string is returned after the entire MIME message is produced. All <span class="structname">mail::Attachment</span> objects must be destroyed immediately afterwards.</p> <p>A <code class="literal">false</code> <em class="parameter"><code>errflag</code></em>, when <code class="function">generate</code>() returns an empty string, indicates that the MIME-formatted message was generated succesfully. A <code class="literal">true</code> <em class="parameter"><code>errflag</code></em> indicated an <code class="literal">errno</code>-related failure to generate the MIME-formatted message.</p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> <p><code class="function">generate</code>() will supply the “<span class="quote">Mime-Version: 1.0</span>” header. This header does not need to be explicitly included in the <em class="parameter"><code>headers</code></em> of the topmost <span class="structname">mail::Attachment</span> object.</p> </div> </div> </div> <div class="refsect1" lang="en" xml:lang="en"> <a id="id640887" shape="rect" name="id640887"> </a> <h2>SEE ALSO</h2> <p><a class="link" href="header-addresslist.html" title="mail::Header::addresslist" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::Header::addresslist</span>(3x)</span></a>, <a class="link" href="header-encoded.html" title="mail::Header::encoded" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::Header::encoded</span>(3x)</span></a>, <a class="link" href="header-mime.html" title="mail::Header::mime" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::Header::mime</span>(3x)</span></a>, <a class="link" href="header-plain.html" title="mail::Header::plain" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::Header::plain</span>(3x)</span></a>.</p> </div> </div> <div class="navfooter"> <hr/> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left" rowspan="1" colspan="1"> <a accesskey="p" href="address.html" shape="rect">Prev</a> </td> <td width="20%" align="center" rowspan="1" colspan="1"> <a accesskey="u" href="misc.html" shape="rect">Up</a></td> <td width="40%" align="right" rowspan="1" colspan="1">  <a accesskey="n" href="emailaddress.html" shape="rect">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::address </td> <td width="20%" align="center" rowspan="1" colspan="1"> <a accesskey="h" href="index.html" shape="rect">Home</a> | <a accesskey="t" href="bk01-toc.html" shape="rect">ToC</a></td> <td width="40%" align="right" valign="top" rowspan="1" colspan="1"> mail::emailAddress</td> </tr> </table> </div> </body> </html>