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