<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::account::readMessageAttributes</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="native.html" title="mail::account Native API reference"/>
<link rel="prev" href="mail-process.html" title="mail::account::process"/>
<link rel="next" href="mail-readmsgcontent.html" title="mail::account::readMessageContent"/>
<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::account::readMessageAttributes</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="mail-process.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
<span class="structname">mail::account</span> Native API
reference</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="mail-readmsgcontent.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" lang="en" xml:lang="en">
<a id="mail-readmsgattr" shape="rect" name="mail-readmsgattr"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::account::readMessageAttributes — Return
message metadata</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="literallayout">
<p><br clear="none"/>
#include <libmail/mail.H><br clear="none"/>
#include <libmail/envelope.H><br clear="none"/>
#include <libmail/structure.H><br clear="none"/>
<br clear="none"/>
class myCallbackMessage : public mail::callback::message {<br clear="none"/>
public:<br clear="none"/>
    void success(std::string msg);<br clear="none"/>
    void fail(std::string msg);<br clear="none"/>
<br clear="none"/>
    void messageEnvelopeCallback(size_t messageNumber,<br clear="none"/>
                                 const <a class="link" href="envelope.html" title="mail::envelope" shape="rect">mail::envelope</a> &envelopeArg);<br clear="none"/>
<br clear="none"/>
    void messageReferencesCallback(size_t messageNumber,<br clear="none"/>
                                   const std::vector<std::string> &referencesArg);<br clear="none"/>
<br clear="none"/>
    void messageArrivalDateCallback(size_t messageNumber,<br clear="none"/>
                                    time_t datetime);<br clear="none"/>
<br clear="none"/>
    void messageSizeCallback(size_t messageNumber,<br clear="none"/>
                             unsigned long size);<br clear="none"/>
<br clear="none"/>
    void messageStructureCallback(size_t messageNumber,<br clear="none"/>
                                  const <a class="link" href="mimestruct.html" title="mail::mimestruct" shape="rect">mail::mimestruct</a> &messageStructure);<br clear="none"/>
    void messageTextCallback(size_t messageNumber, std::string text);<br clear="none"/>
};<br clear="none"/>
<br clear="none"/>
std::cout << (float)myMessageCallback.messageTextCompleted /<br clear="none"/>
             (float)myMessageCallback.messageTextEstimatedSize * 100<br clear="none"/>
          << "% completed." << endl;<br clear="none"/>
<br clear="none"/></p>
</div>
<div class="literallayout">
<p><br clear="none"/>
mail::account *account;<br clear="none"/></p>
</div>
<div class="funcsynopsis">
<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
<tr>
<td rowspan="1" colspan="1"><code class="funcdef">account-><b class="fsfunc">readMessageAttributes</b>(</code></td>
<td rowspan="1" colspan="1">const
std::vector<size_t>  </td>
<td rowspan="1" colspan="1"><var class="pdparam">msgList</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">
mail::account::MessageAttributes  </td>
<td rowspan="1" colspan="1"><var class="pdparam">attributes</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">myCallbackMessage
& </td>
<td rowspan="1" colspan="1"><var class="pdparam">callback</var><code>)</code>;</td>
</tr>
</table>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id598085" shape="rect" name="id598085"> </a>
<h2>USAGE</h2>
<p><code class="function">mail::account::readMessageAttributes</code>
requests metadata of messages in the currently open folder.
<em class="parameter"><code>msgList</code></em> specifies a
list of messages. Messages are numbered starting with message
#0 and up to one less than <a class="link" href="mail-getfolderindexsize.html" title="mail::account::getFolderIndexSize" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexSize</span>(3x)</span></a>()
(when <code class="function">mail::account::getFolderIndexSize</code> returns
6, the messages are numbered 0 through 5). Only the messages
that appear in <em class="parameter"><code>msgList</code></em> are processed by this
request. <em class="parameter"><code>attributes</code></em>
is a logical-or of the following constants:</p>
<div class="variablelist">
<dl>
<dt><span class="term">mail::account::ARRIVALDATE</span></dt>
<dd>
<p>When the message was added to the folder
(<code class="function">myCallback.messageArrivalDateCallback</code>).</p>
</dd>
<dt><span class="term">mail::account::MESSAGESIZE</span></dt>
<dd>
<p>Estimated message size, in bytes (<code class="function">myCallback.messageSizeCallback</code>).</p>
</dd>
<dt><span class="term">mail::account::ENVELOPE</span></dt>
<dd>
<p>Message's envelope headers (<code class="function">myCallback.messageEnvelopeCallback</code>,
and possibly <code class="function">myCallback.messageReferencesCallback</code>).
<code class="function">messageEnvelopeCallback</code>
receives a <a class="link" href="envelope.html" title="mail::envelope" shape="rect"><span class="structname">mail::envelope</span></a> object that
describes the "envelope", or a message summary (sender,
recipients, subject, etc...). In some instances the
<code class="function">messageReferencesCallback</code>
callback will also be invoked, with an an array of
message IDs taken from the <code class="literal">References</code> header. In other instances
the <span class="structname">mail::envelope</span> will
already have the <em class="structfield"><code>references</code></em> populated
with the same information.</p>
<p><code class="function">messageReferencesCallback</code> may be
invoked before or after the <code class="function">messageEnvelopeCallback</code> function, if
at all. The application should be prepared to merge the
information returned by these two callbacks. As noted
below, multiple callback methods may be invoked in any
order, and the application should not make any
assumption as to the relative order in which these two
methods will be invoked.</p>
<p>For example, it is perfectly feasible to have a
request for envelopes of two messages result in two
<code class="function">messageEnvelopeCallback</code>
callbacks, then two <code class="function">messageReferencesCallback</code> callbacks;
or two instances of <code class="function">messageEnvelopeCallback</code> followed by a
<code class="function">messageReferencesCallback</code>
that refers to the same message.</p>
</dd>
<dt><span class="term">mail::account::MIMESTRUCTURE</span></dt>
<dd>
<p>Returns a <a class="link" href="mimestruct.html" title="mail::mimestruct" shape="rect"><span class="structname">mail::mimestruct</span></a> object that
enumerates the message's MIME content (<code class="function">myCallback.messageStructureCallback</code>).
<code class="function">myCallback.messageStructureCallback</code>
receives a reference to a <a class="link" href="mimestruct.html" title="mail::mimestruct" shape="rect"><span class="structname">mail::mimestruct</span></a> object that
refers to the entire message. If the message contains
attachments, the <code class="function">mail::mimestruct::getChild</code> method
returns pointers to <a class="link" href="mimestruct.html" title="mail::mimestruct" shape="rect"><span class="structname">mail::mimestruct</span></a> objects which
refer to the individual MIME attachments.</p>
</dd>
</dl>
</div>
<p>Metadata information requested by each one of these
constants is returned by invoking the corresponding callback
method in <em class="parameter"><code>callback</code></em>.
When requesting two or more items at once the callback
functions may be invoked in any order. When requesting
metadata from more than one message the callback functions
are invoked one for each requested message. Each callback
function receives the requested metadata item together with
<em class="parameter"><code>messageNumber</code></em> - which
message this metadata item relates to. The callback functions
may be invoked in any message order.</p>
<p>For example, when requesting both <code class="literal">ENVELOPE</code> and <code class="literal">MIMESTRUCTURE</code>, the possibilities are:</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p><code class="literal">ENVELOPE</code>s for all
messages first, then all <code class="literal">MIMESTRUCTURE</code>s.</p>
</li>
<li>
<p>The <code class="literal">ENVELOPE</code> and the
<code class="literal">MIMESTRUCTURE</code> for the
first message, then the <code class="literal">ENVELOPE</code> and the <code class="literal">MIMESTRUCTURE</code> for the next message,
and so on.</p>
</li>
</ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The <span class="structname">mail::envelope</span> and
<a class="link" href="mimestruct.html" title="mail::mimestruct" shape="rect"><span class="structname">mail::mimestruct</span></a> objects are
destroyed immediately after their corresponding callback
method terminates. The application should copy any objects
it intends to use later.</p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id598266" shape="rect" name="id598266"> </a>
<h2>Return Codes</h2>
<p>The application must wait until <em class="parameter"><code>callback</code></em>'s <code class="function">success</code> or <code class="function">fail</code> method is invoked. The <code class="function">success</code> method is invoked when this request
is succesfully processed. The <code class="function">fail</code> method is invoked if this request
cannot be processed. The application must not destroy
<em class="parameter"><code>callback</code></em> until either
the <code class="function">success</code> or <code class="function">fail</code> method is invoked.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><em class="parameter"><code>callback</code></em>'s
<code class="function">fail</code> method may be invoked
even after other callback methods were invoked. This
indicates that the request was partially completed before
the error was encountered.</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Multiple applications may have the same account and
folder opened at the same time. It is possible that a
message referenced by this request was already deleted by
another application. Depending on the underlying server
implementation this will result in either a failed request,
invoking <code class="function">callback.fail</code>, or
the request completing (<code class="function">callback.success</code> invoked) but without
invoking any callback function that refer to the
message.</p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id598389" shape="rect" name="id598389"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="mail-getfolderindexsize.html" title="mail::account::getFolderIndexSize" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexSize</span>(3x)</span></a>,
<a class="link" href="mail-readmsgcontent.html" title="mail::account::readMessageContent" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::readMessageContent</span>(3x)</span></a>,
<a class="link" href="mail-readmsgcontentdecoded.html" title="mail::account::readMessageContentDecoded" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::readMessageContentDecoded</span>(3x)</span></a>,
<a class="link" href="mail-getfolderindexinfo.html" title="mail::account::getFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexInfo</span>(3x)</span></a>,
<a class="link" href="envelope.html" title="mail::envelope" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::envelope</span>(3x)</span></a>,
<a class="link" href="mimestruct.html" title="mail::mimestruct" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::mimestruct</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="mail-process.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="native.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="mail-readmsgcontent.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::account::process </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::account::readMessageContent</td>
</tr>
</table>
</div>
</body>
</html>
