<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::folder::open</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="libmail-folder.html" title="mail::folder Native API reference"/>
<link rel="prev" href="folder-isparentof.html" title="mail::folder::isparentof"/>
<link rel="next" href="folder-readfolderinfo.html" title="mail::folder::readFolderInfo"/>
<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::folder::open</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="folder-isparentof.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
<span class="structname">mail::folder</span> Native API
reference</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="folder-readfolderinfo.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" lang="en" xml:lang="en">
<a id="folder-open" shape="rect" name="folder-open"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::folder::open — Open a folder</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="literallayout">
<p><br clear="none"/>
<br clear="none"/>
<br clear="none"/>
<br clear="none"/>
#include <libmail/mail.H><br clear="none"/>
<br clear="none"/>
<br clear="none"/>
class myCallback : public mail::callback {<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"/></p>
</div>
<div class="literallayout">
<p><br clear="none"/>
#include <libmail/snapshot.H><br clear="none"/>
<br clear="none"/>
class myFolderCallback : public mail::callback::folder {<br clear="none"/>
<br clear="none"/>
public:<br clear="none"/>
    void newMessages();<br clear="none"/>
<br clear="none"/>
    void messagesRemoved(vector< pair<size_t, size_t> > &removedList);<br clear="none"/>
<br clear="none"/>
    void messageChanged(size_t messageNumber);<br clear="none"/>
<br clear="none"/>
    void saveSnapshot(std::string snapshotId);<br clear="none"/>
    <br clear="none"/>
};<br clear="none"/>
<br clear="none"/>
class myRestoreSnapshot : public mail::snapshot {<br clear="none"/>
<br clear="none"/>
public:<br clear="none"/>
    void getSnapshotInfo(std::string &snapshotId,<br clear="none"/>
                         size_t &nMessages);<br clear="none"/>
<br clear="none"/>
    void restoreSnapshot(mail::snapshot::restore &restoreCB);<br clear="none"/>
};<br clear="none"/>
<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">folder-><b class="fsfunc">open</b>(</code></td>
<td rowspan="1" colspan="1">myCallback & </td>
<td rowspan="1" colspan="1"><var class="pdparam">callback</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">myRestoreSnapshot
& </td>
<td rowspan="1" colspan="1"><var class="pdparam">restoreSnapshot</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">myFolderCallback
& </td>
<td rowspan="1" colspan="1"><var class="pdparam">folderCallback</var><code>)</code>;</td>
</tr>
</table>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id628716" shape="rect" name="id628716"> </a>
<h2>USAGE</h2>
<p>A mail folder must be formally "opened" before the
messages in the folder may be accessed. Each mail account can
have only one mail folder at any time Opening another folder
automatically "closes" the previous folder.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Different <span class="structname">mail::account</span>
or <span class="structname">mail::ACCOUNT</span> objects
may each have a folder opened, at the same time. It is
possible to create multiple <span class="structname">mail::account</span> or <span class="structname">mail::ACCOUNT</span> objects that refer to the
same actual mail account. Whether it is possible to access
the same account multiple times, using different objects,
and whether each object may have the same folder opened
depends on the account type and/or the remote server.</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>Whether it's possible to open the same remote IMAP
or POP3 account more than once depends on the remote
IMAP/POP3 server.</p>
</li>
<li>
<p>Whether it's possible to open the same folder on a
remote IMAP server account more than once depends on
the remote IMAP/POP3 server. Most IMAP servers allow
the same account to be opened more than once, as long
as the different login sessions do not try to open
the same folder. Some IMAP servers allow the same
folder to be opened simultaneously by multiple
sessions.</p>
</li>
<li>
<p>It is generally possible to open the same local
mail folder simultaneously, via multiple <span class="structname">mail::account</span> objects, as long as
only one pending request is issued at a time.
Concurrent access to local maildirs generally works
well, however simultaneous access to the same mbox
folder may be rather slow, due to the overhead of
locking and rescanning of the folder by each
<span class="structname">mail::account</span>
object.</p>
</li>
</ul>
</div>
</div>
<p>Any previously-opened folder is closed before the an
attempt to open this folder is made. If the new folder cannot
be opened, the previous folder is still considered
closed.</p>
<div class="refsect2" lang="en" xml:lang="en">
<a id="id628806" shape="rect" name="id628806"> </a>
<h3>Folder Updates</h3>
<p>The <em class="parameter"><code>folderCallback</code></em> object is used
to notify the application of changes to the folder's
contents. The application must not destroy <em class="parameter"><code>folderCallback</code></em> until either
the <span class="structname">mail::account</span> is
destroyed, or another folder is opened. Changes to the
folder's contents are reflected by invoking <em class="parameter"><code>folderCallback</code></em>'s methods.</p>
<p><em class="parameter"><code>folderCallback</code></em>'s
methods are usually invoked by <a class="link" href="mail-removemessages.html" title="mail::account::removeMessages" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::removeMessages</span>(3x)</span></a>,
<a class="link" href="mail-updatefolderindexinfo.html" title="mail::account::updateFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::updateFolderIndexInfo</span>(3x)</span></a>,
<a class="link" href="mail-savefolderindexinfo.html" title="mail::account::saveFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::saveFolderIndexInfo</span>(3x)</span></a>,
<a class="link" href="mail-updatefolderindexflags.html" title="mail::account::updateFolderIndexFlags" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::updateFolderIndexFlags</span>(3x)</span></a>,
and <a class="link" href="mail-checknewmail.html" title="mail::account::checkNewMail" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::checkNewMail</span>(3x)</span></a>,
however the application must be prepared to handle any
<em class="parameter"><code>folderCallback</code></em>'s
method to be invoked at any time. Most mail servers reserve
the right to notify the client of changes to the folder's
contents at any time.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>As always, messages are numbered starting with 0. That
is, a folder with ten messages contains messages #0
through #9.</p>
</div>
<div class="variablelist">
<dl>
<dt><span class="term">void newMessages()</span></dt>
<dd>
<p>This method is invoked whenever new messages are
added to the currently open folder. The application
should use <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>
to determine how many messages now exist in the
current folder, and use the number of messages the
application already knows about to determine how many
new messages have been added.</p>
<p>Example: The application already knows that the
folder has three messages. After <code class="function">mail::callback::folder::newMessages</code>
is invoked <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>
now claims there are five messages in the folder.
This means that the last two messages in the folder
are new messages.</p>
</dd>
<dt><span class="term">void messagesRemoved(vector<
pair<size_t, size_t> >
&removedList);</span></dt>
<dd>
<p>Messages were removed from the folder, and the
remaining messages have been renumbered to fill in
the gaps. <em class="parameter"><code>removedList</code></em> is an array
that lists which messages were removed. Each array
element contains a starting range and an ending
range. The range “<span class="quote"><code class="literal">7-9</code></span>” specifies that
messages #7 through #9, three messages overall, were
removed. The range “<span class="quote"><code class="literal">5-5</code></span>” specifies that
message #5 was removed.</p>
<p>The remaining messages have been renumbered. For
example, if the application knows that the folder has
ten messages, then if <em class="parameter"><code>removedList</code></em> contains
two ranges: “<span class="quote"><code class="literal">3-3</code></span>”, and
“<span class="quote"><code class="literal">5-7</code></span>”, this indicates
that messages #3, #5, #6, and #7 were removed. The
old message #4 is now message #3, the old mesasge #8
is now message #4, and the old message #9 is now
message #5, and there are now six messages left in
the folder.</p>
</dd>
<dt><span class="term">void messageChanged(size_t
messageNumber)</span></dt>
<dd>
<p>The flags of the indicated message have changed.
The application should use <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>
to read the current message flags.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect2" lang="en" xml:lang="en">
<a id="id629080" shape="rect" name="id629080"> </a>
<h3>Snapshots</h3>
<p>Folder index snapshots are implemented by some mail
account types. Folder index snapshots allow large folders
to be opened quickly. If a folder contains many messages,
<span class="application">LibMAIL</span> may take a long
time to open a folder. Folder index snapshots speed up the
process of opening a folder which was recently opened. At
this time, folder index snapshots are implemented with
<code class="literal">NNTP</code>, <code class="literal">pop3</code>, and <a class="link" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1" shape="rect"><code class="literal">SMAP</code></a>-based
accounts. Attempts to use folder index snapshots with other
account types will be quietly ignored.</p>
<p>Implementing folder index snapshots is optional.
<em class="parameter"><code>restoreSnapshot</code></em> may
be <code class="literal">NULL</code>, and <span class="application">Cone</span> will open folder the
old-fashional way, by patiently downloading the entire
folder index when opening the folder. To implement
snapshots the application must implemented the <code class="function">saveSnapshot</code> method of its <span class="structname">mail::callback::folder</span> subclass, then
pass a pointer to a <span class="structname">mail::snapshot</span> subclass to <code class="function">mail::folder::open</code></p>
<p>Applications can pass a <code class="literal">NULL</code> pointer, and not define <code class="function">saveSnapshot</code> if folder index snapshots
are not needed. If <code class="function">mail::folder::open</code> receives a
non-<code class="literal">NULL</code> pointer, the object
must not be destroyed until <em class="parameter"><code>callback</code></em>'s <code class="function">success</code> or <code class="function">fail</code> method is invoked.</p>
<p>When snapshots are enabled, <span class="application">LibMAIL</span> invokes <code class="function">mail::callback::folder::saveSnapshot</code>
whenever a snapshot of the opened folder's index should be
saved. <code class="function">mail::callback::folder::saveSnapshot</code> gets
invoked periodically as long as the folder remains open.
<code class="function">mail::callback::folder::saveSnapshot</code>
receives an opaque identifier, <em class="parameter"><code>snapshotId</code></em>. <code class="function">mail::callback::folder::saveSnapshot</code>
should use <a class="link" href="account-getfolderindexsize.html" title="mail::ACCOUNT::getFolderIndexSize" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexSize</span>(3x)</span></a>
to obtain the number of messages in the folder, then use
<a class="link" href="account-getfolderindexinfo.html" title="mail::ACCOUNT::getFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexInfo</span>(3x)</span></a>
to save each message's folder index entry, alongside with
the <em class="parameter"><code>snapshotId</code></em>, and
the total number of messages.</p>
<p><span class="structname">mail::messageInfo</span> has a
convenient <code class="function">operator string()</code>
that converts the entire object into a string, and a
corresponding constructor that initializes the entire
<span class="structname">mail::messageInfo</span> object
from a string.</p>
<p>The application needs only to save the most recent
snapshot. <code class="function">mail::callback::folder::saveSnapshot</code>
should discard any previously-saved snapshot, and replace
it with the current one. <code class="function">mail::callback::folder::saveSnapshot</code>
should not invoke any other <span class="application">LibMAIL</span> methods, except <span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexSize</span>(3x)</span>
and <span class="citerefentry"><span class="refentrytitle">mail::account::getFolderIndexInfo</span>(3x)</span>.</p>
<p>The <span class="structname">mail::snapshot</span>-subclassed object passed
to <code class="function">mail::folder::open</code>
implements two methods: <code class="function">getSnapShotInfo</code> and <code class="function">restoreSnapshot</code>. <code class="function">getSnapShotInfo</code> should initialize
<em class="parameter"><code>snapshotId</code></em> to the
opaque snapshot identifier of the most-recently saved
snapshot, and <em class="parameter"><code>nMessages</code></em> to the number of
messages in the snapshot.</p>
<p>An application that does not have a snapshot, but wishes
to use snapshots (perhaps this is the very first time this
folder was opened) should initialize <em class="parameter"><code>snapshotId</code></em> to an empty
string, and set <em class="parameter"><code>nMessages</code></em> to zero. The
application should not pass a <code class="literal">NULL</code> <em class="parameter"><code>restoreSnapshot</code></em> parameter,
since that disables <span class="application">LibMAIL</span> 's usage of snapshots.</p>
<p>After invoking <code class="function">getSnapShotInfo</code>, <span class="application">LibMAIL</span> will invoke <code class="function">restoreSnapshot</code>, at which time the
application needs to restore the folder index as it was
saved by the snapshot. <code class="function">restoreSnapshot</code> receives a reference to a
<span class="structname">mail::snapshot::restore</span>
object, which contains two methods:</p>
<div class="variablelist">
<dl>
<dt><span class="term">void restoreIndex(size_t msgNum,
const mail::messageInfo &msgInfo);</span></dt>
<dd>
<p>Repeatedly invoke this function to specify the
previously saved <span class="structname">mail::messageInfo</span> of each
message.</p>
</dd>
<dt><span class="term">void abortRestore()</span></dt>
<dd>
<p>After restoring the entire folder index,
<code class="function">restoreSnapshot</code> should
simply terminate. If the application cannot restore
the entire folder index, for some reason,
<code class="function">abortRestore</code> should be
invoke to invalidate any partially-restored index
data.</p>
</dd>
</dl>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>With <code class="literal">POP3</code> accounts,
message status flags are going to be preserved only when
snapshots are used. The <code class="literal">POP3</code>
does not provide any facility for saving message status
flags; and without snapshots each time a <code class="literal">POP3</code> folder is opened all messages will
be seen as new messages. Using snapshots saves each
message's status, and restores it when the <code class="literal">POP3</code> folder is reopened.</p>
</div>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id629581" shape="rect" name="id629581"> </a>
<h2>RETURN CODES AND CALLBACKS</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>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id629673" shape="rect" name="id629673"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="folder-readfolderinfo.html" title="mail::folder::readFolderInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::readFolderInfo</span>(3x)</span></a>,
<a class="link" href="mail-checknewmail.html" title="mail::account::checkNewMail" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::checkNewMail</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="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-removemessages.html" title="mail::account::removeMessages" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::removeMessages</span>(3x)</span></a>,
<a class="link" href="mail-savefolderindexinfo.html" title="mail::account::saveFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::saveFolderIndexInfo</span>(3x)</span></a>,
<a class="link" href="mail-updatefolderindexflags.html" title="mail::account::updateFolderIndexFlags" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::updateFolderIndexFlags</span>(3x)</span></a>,
<a class="link" href="mail-updatefolderindexinfo.html" title="mail::account::updateFolderIndexInfo" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::updateFolderIndexInfo</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="folder-isparentof.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="libmail-folder.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="folder-readfolderinfo.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::folder::isparentof </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::folder::readFolderInfo</td>
</tr>
</table>
</div>
</body>
</html>
