<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::folder::createSubFolder</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-create.html" title="mail::folder::create"/>
<link rel="next" href="folder-delrights.html" title="mail::folder::delRights"/>
<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::createSubFolder</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="folder-create.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-delrights.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" lang="en" xml:lang="en">
<a id="folder-createsubfolder" shape="rect" name="folder-createsubfolder"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::folder::createSubFolder — Create a new
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"/>
class myFolderCallback : public mail::callback::folderlist {<br clear="none"/>
public:<br clear="none"/>
    void success(const std::vector<const mail::folder *> &folders);<br clear="none"/>
};<br clear="none"/></p>
</div>
<div class="literallayout">
<p><br clear="none"/>
mail::folder *folder;<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">createSubFolder</b>(</code></td>
<td rowspan="1" colspan="1">std::string  </td>
<td rowspan="1" colspan="1"><var class="pdparam">name</var>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">bool  </td>
<td rowspan="1" colspan="1"><var class="pdparam">createDirectory</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>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">myCallback & </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="id618647" shape="rect" name="id618647"> </a>
<h2>USAGE</h2>
<p>Most mail accounts support the ability to create and
delete folders, which are arranged in a tree-like hierarchy.
<code class="function">mail::folder::createSubFolder</code>
creates a new folder, as a subfolder of <em class="parameter"><code>folder</code></em> (which does not
necessarily have to refer the currently open folder; it may
be any <span class="structname">mail::folder</span> object
that's associated with an active <span class="structname">mail::account</span>).</p>
<p>Folders may be created in IMAP accounts, and local mail
(either mbox or maildir) accounts. Folders cannot be created
in POP3 accounts, as this functionality is not supported by
the POP3 protocol (this operation will fail).</p>
<p>There are two types of folders: folder that contain
messages (regular folders), and folders that contain other
sub-folders ("folder directories", or "directories" for
short). <em class="parameter"><code>isDirectory</code></em>
specifies whether the new folder is a regular folder, or a
folder directory.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Local maildir-based accounts, and some IMAP servers, are
capable of supporting so-called "dual-purpose" folders;
folders that contain both messages and other sub-folders. A
dual-purpose folder may be created by invoking <code class="function">mail::folder::createSubFolder</code> twice, once
with <em class="parameter"><code>isDirectory</code></em>
set to <code class="literal">false</code>; and a second
time with <em class="parameter"><code>isDirectory</code></em> set to
<code class="literal">true</code>, specifying the same
<em class="parameter"><code>name</code></em> both
times.</p>
</div>
<p><em class="parameter"><code>name</code></em> specifies the
name of the new folder, in the application's character
set.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Some mail servers reserve certain characters which
cannot be used in folder names. IMAP mail servers use a
special character (usually "<code class="literal">/</code>"
or "<code class="literal">.</code>") as a separator between
names in a hierarchical folder path. The actual character
varies from server to server. An attempt to create/rename a
folder whose name includes a reserved character will fail.
Different IMAP servers use different hierarchy separator
characters. An attempt to create a folder may fail on one
IMAP server even if another IMAP server can succesfully
create a folder with the same name. This is, unfortunately,
a design flaw in the IMAP protocol.</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Maildir folders created by are compatible and can be
read by the <a class="ulink" href="http://www.courier-mta.org" target="_top" shape="rect">Courier-IMAP</a> server. Names of maildir folders
may contain any character, including the characters
"<code class="literal">:</code>", "<code class="literal">/</code>", "<code class="literal">.</code>",
"<code class="literal">~</code>", and "<code class="literal">:</code>". However, if the same folders are
exported via IMAP, folders whose name includes these
characters may not be readable by some IMAP clients. Even a
<span class="application">LibMAIL</span> application may
not be able to read one of these folders via IMAP.</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Mbox mail folders created by <span class="application">LibMAIL</span> are mostly compatible and can
be exported by IMAP servers that read mbox-formatted mail
folders (with some limitations, such as that the same mbox
folder cannot be open by <span class="application">LibMAIL</span> and another application at the
same time). Names of mbox folders can contain any
character, including the characters "<code class="literal">/</code>", and "<code class="literal">~</code>".
However if mbox folders are exported via IMAP, folders
whose name includes these characters may not be readable by
some IMAP clients.</p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id618896" shape="rect" name="id618896"> </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 class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The application must not destroy <em class="parameter"><code>folderCallback</code></em> until this
request fails or succeeds. <em class="parameter"><code>folderCallback</code></em>'s <code class="function">success</code> method is invoked just before the
<em class="parameter"><code>callback</code></em>'s
<code class="function">success</code> method.</p>
</div>
<p>If the folder was succesfully created, the <code class="function">folderCallback.success</code> method receives a
vector that contains a single pointer to a <span class="structname">mail::folder</span> object. The <span class="structname">mail::folder</span> object will refer to the
newly-created folder.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><span class="structname">mail::folder</span>s are linked
to their corresponding <span class="structname">mail::account</span>s. A <span class="structname">mail::folder</span> created by one
<span class="structname">mail::account</span> may not be
used with a different <span class="structname">mail::folder</span>. All <span class="structname">mail::folder</span>s created by a <span class="structname">mail::account</span> are invalidated when this
<span class="structname">mail::account</span> object is
destroyed. Note that the <span class="structname">mail::folder</span> objects are not
automatically destroyed; the application is still
responsible for destroying any remaining <span class="structname">mail::folder</span>s, after their a
<span class="structname">mail::account</span> is
destroyed.</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The <code class="function">folderCallback.success</code>
method receives a (possibly empty) vector of pointers to
<span class="structname">mail::folder</span> objects. These
objects will be destroyed when <code class="function">folderCallback.success</code> terminates. The
application must use <a class="link" href="folder-clone.html" title="mail::folder::clone" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::clone</span>(3x)</span></a>
to create copies of <span class="structname">mail::folder</span> objects it wants to use
later.</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Both <code class="function">folderCallback.success</code> and <code class="function">myCallback.success</code> method will be invoked
if this request succeeds. <code class="function">folderCallback.success</code> will be invoked
before <code class="function">myCallback.success</code>
(since by definition this indicates that the request has
been completed).</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>For some kinds of accounts, <a class="link" href="folder-readsubfolders.html" title="mail::folder::readSubFolders" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::readSubFolders</span>(3x)</span></a>
may not enumerate new folder directories until they contain
at least one folder. Therefore the recommended process to
create a new folder directory is as follows:</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>Invoke <code class="function">mail::folder::createSubFolder</code> to
request the creation of a new folder directory.</p>
</li>
<li>
<p>In <code class="function">folderCallback.success</code>, use
<a class="link" href="folder-clone.html" title="mail::folder::clone" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::clone</span>(3x)</span></a>
to save a copy of the <span class="structname">mail::folder</span> object which refers
to the new folder directory.</p>
</li>
<li>
<p>After the <code class="function">myCallback.success</code> method is
invoked, use the saved <span class="structname">mail::folder</span> object's
<code class="function">createSubFolder</code> method
to create a new folder in the new folder
directory.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id619285" shape="rect" name="id619285"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="folder-clone.html" title="mail::folder::clone" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::clone</span>(3x)</span></a>,
<a class="link" href="folder-create.html" title="mail::folder::create" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::create</span>(3x)</span></a>,
<a class="link" href="folder-destroy.html" title="mail::folder::destroy" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::destroy</span>(3x)</span></a>,
<a class="link" href="folder-readsubfolders.html" title="mail::folder::readSubFolders" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::readSubFolders</span>(3x)</span></a>,
<a class="link" href="folder-renamefolder.html" title="mail::folder::renameFolder" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::folder::renameFolder</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-create.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-delrights.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::folder::create </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::delRights</td>
</tr>
</table>
</div>
</body>
</html>
