<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>
