<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::account::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="native.html" title="mail::account Native API reference"/>
<link rel="prev" href="mail-movemessagesto.html" title="mail::account::moveMessagesTo"/>
<link rel="next" href="mail-poll.html" title="mail::account::poll"/>
<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::open</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="mail-movemessagesto.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-poll.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" lang="en" xml:lang="en">
<a id="mail-open" shape="rect" name="mail-open"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::account::open — Open a new mail account</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"/>
<br clear="none"/>
class myDisconnectCallback : public mail::callback::disconnect {<br clear="none"/>
public:<br clear="none"/>
    void disconnected(const char *msg);<br clear="none"/>
    void servererror(const char *msg);<br clear="none"/>
};<br clear="none"/>
<br clear="none"/>
#include <libmail/logininfo.H><br clear="none"/>
<br clear="none"/>
class myPromptCallback : public mail::loginCallback {<br clear="none"/>
public:<br clear="none"/>
   void loginPrompt(mail::loginCallback::callbackType, std::string);<br clear="none"/>
};<br clear="none"/>
<br clear="none"/>
void myPromptCallback::loginPrompt(mail::loginCallback::callbackType cbType,<br clear="none"/>
                                   string prompt)<br clear="none"/>
{<br clear="none"/>
    struct termios ti, ti2;<br clear="none"/>
<br clear="none"/>
    cout << prompt << flush;<br clear="none"/>
<br clear="none"/>
    tcgetattr(0, &ti);<br clear="none"/>
<br clear="none"/>
    ti2=ti;<br clear="none"/>
<br clear="none"/>
    if (cbType == PASSWORD)<br clear="none"/>
    {<br clear="none"/>
        ti2.c_lflag &= ~ECHO;<br clear="none"/>
        tcsetattr(0, TCSAFLUSH, &ti2);<br clear="none"/>
    }<br clear="none"/>
<br clear="none"/>
    std::string reply;<br clear="none"/>
<br clear="none"/>
    if (getline(cin, reply).fail())<br clear="none"/>
    {<br clear="none"/>
       callbackCancel();<br clear="none"/>
       return;<br clear="none"/>
    }<br clear="none"/>
<br clear="none"/>
    if (cbType != USERID)  // It's PASSWORD<br clear="none"/>
        tcsetattr(0, TCSAFLUSH, &ti);<br clear="none"/>
<br clear="none"/>
    callback(reply);<br clear="none"/>
}<br clear="none"/>
<br clear="none"/>
mail::account::openInfo accountOpenInfo;<br clear="none"/>
myPromptCallback passwdCallback;<br clear="none"/>
<br clear="none"/>
    accountOpenInfo.url="imap://john@imap.example.com/novalidate-cert";<br clear="none"/>
    accountOpenInfo.pwd="secret";<br clear="none"/>
    accountOpenInfo.certificates.push_back(pemCertStr);<br clear="none"/>
    accountOpenInfo.extraString=""; // Used by nntp:, nntps:, pop3maildrop: and pop3maildrops:<br clear="none"/>
    accountOpenInfo.loginCallbackObj= &passwdCallback;<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">mail::account *account=<b class="fsfunc">mail::account::open</b>(</code></td>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1"><var class="pdparam">accountOpenInfo</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>,</td>
</tr>
<tr>
<td rowspan="1" colspan="1"> </td>
<td rowspan="1" colspan="1">myDisconnectCallback
& </td>
<td rowspan="1" colspan="1"><var class="pdparam">disconnectCallback</var><code>)</code>;</td>
</tr>
</table>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id592507" shape="rect" name="id592507"> </a>
<h2>USAGE</h2>
<p><code class="function">mail::account::open</code> opens a
mail account on a server. <em class="parameter"><code>url</code></em> identifies the account.
<em class="parameter"><code>url</code></em> should contain a
text string that identifies one of the following types of
accounts:</p>
<div class="variablelist">
<dl>
<dt><span class="term">imap://<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>An <a class="ulink" href="http://www.rfc-editor.org/rfc/rfc3501.txt" target="_top" shape="rect">IMAP</a> or an <a class="link" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1" shape="rect">SMAP</a> account on <em class="replaceable"><code>server</code></em>. The colon and
<em class="replaceable"><code>port</code></em> are
optional; defaulting to the standard IMAP port 143. A
slash, followed by a slash-separated list of <a class="link" href="mail-open.html#mail-open-options" title="Account Options" shape="rect">additional options</a>
may follow.</p>
<p><em class="replaceable"><code>user</code></em>
identifies the account login id. <em class="replaceable"><code>user</code></em> may contain any
characters except <code class="literal">/</code>,
<code class="literal">@</code>, <code class="literal">%</code>, and <code class="literal">:</code>.
These characters may be specified by using <code class="literal">%</code>, followed by a two-digit uppercase
hexadecimal ASCII code for the character.</p>
</dd>
<dt><span class="term">pop3://<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>A POP3 account on <em class="replaceable"><code>server</code></em>. The colon and
<em class="replaceable"><code>port</code></em> are
optional; defaulting to the standard POP3 port 110. A
slash, followed by a slash-separated list of <a class="link" href="mail-open.html#mail-open-options" title="Account Options" shape="rect">additional options</a>
may follow.</p>
<p><em class="replaceable"><code>user</code></em>
identifies the account login id. <em class="replaceable"><code>user</code></em> may contain any
characters except <code class="literal">/</code>,
<code class="literal">@</code>, <code class="literal">%</code>, and <code class="literal">:</code>.
These characters may be specified by using <code class="literal">%</code> followed by a two-digit uppercase
hexadecimal ASCII code for the character.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The POP3 server must support the <code class="literal">UIDL</code> command, which is implemented
by all modern POP3 servers. Some very old POP3
servers may not support this command, in which case
use a <code class="literal">pop3maildrop</code> URL
instead.</p>
</div>
</dd>
<dt><span class="term">pop3maildrop://<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>Like “<span class="quote">pop3</span>”,
except that messages are downloaded, then deleted, from
the POP3 server. Use “<span class="quote">pop3maildrop</span>” maildrop when the
remote server does not implement the <code class="literal">UIDL</code> command.</p>
<p><em class="parameter"><code>extraString</code></em>
must be initialized to the name of a maildir where
messages from the POP3 server will be downloaded to. If
the maildir does not exist, it will be automatically
created.</p>
</dd>
<dt><span class="term">nntp://<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>Access Usenet newsgroups via nntp on <em class="replaceable"><code>server</code></em>. The colon and
<em class="replaceable"><code>port</code></em> are
optional; defaulting to the standard NNTP port 119. A
slash, followed by a slash-separated list of <a class="link" href="mail-open.html#mail-open-options" title="Account Options" shape="rect">additional options</a>
may follow.</p>
<p><em class="parameter"><code>extraString</code></em>
must be initialized to the name of a file where the
list of subscribed newsgroups, and read articles, will
be saved.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><span class="application">LibMAIL</span> uses a
slightly expanded version of the traditional
<code class="filename">.newsrc</code> format,
containing some extra header information.</p>
</div>
<p><em class="replaceable"><code>user</code></em> and
<em class="replaceable"><code>pwd</code></em> should be
specified if the NNTP server requires authentication.
Otherwise these parameters may be omitted.</p>
</dd>
<dt><span class="term">imaps://<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>Like "imap", but use encryption to connect to the
IMAP/SMAP server, and use the default <code class="literal">imaps</code> port (usually 993).</p>
</dd>
<dt><span class="term">pop3s://<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>Like “<span class="quote">pop3</span>”,
but use encryption to connect to the POP3 server, and
use the default <code class="literal">pop3s</code> port
(usually 995).</p>
</dd>
<dt><span class="term">pop3maildrops://<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>Like “<span class="quote">pop3maildrop</span>”, but use encryption
to connect to the POP3 server, and use the default
<code class="literal">pop3s</code> port (usually
995).</p>
</dd>
<dt><span class="term">nntps://<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>Like "nntp", but use encryption to connect to the
NNTP server, and use the default <code class="literal">nntps</code> port (usually 563).</p>
</dd>
<dt><span class="term">maildir:[<span class="optional">path</span>]</span></dt>
<dd>
<p>Mail in a local maildir. [<span class="optional">path</span>] specifies the path to the
maildir-type mailbox. [<span class="optional">path</span>] may be a relative path,
anchored at the home directory (NOT the process's
current directory). <code class="literal">"maildir:Maildir"</code> is the usual way to
open <code class="filename">$HOME/Maildir</code>.</p>
</dd>
<dt><span class="term">mail:[<span class="optional">path</span>]</span></dt>
<dd>
<p>Open mail in a local mailbox. [<span class="optional">path</span>] specifies the path to a file or
a directory containing mbox-type mailboxes.
[<span class="optional">path</span>] may be a relative
path, anchored at the home directory (NOT the process's
current directory). [<span class="optional">path</span>] may refer to a directory, in
which case the directory's contents are read as
mbox-type folders. <code class="literal">"maildir:Mail"</code> is the usual way to
open mail in <code class="filename">$HOME/Mail</code>.</p>
</dd>
<dt><span class="term">inbox:[<span class="optional">path</span>]</span></dt>
<dd>
<p>Open mail in a local mailbox. This is the same as
<code class="literal">"mail:[<span class="optional">path</span>]"</code>, with the additional
inclusion of the default system mailbox (usually in
<code class="filename">/var/spool/mail</code>),
represented by the special folder named <code class="literal">INBOX</code>.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The default system mailbox is implemented by
creating <code class="filename">$HOME/Inbox</code>,
and automatically copying all mail from the default
system mailbox to <code class="filename">$HOME/Inbox</code> (which is represented
as the <code class="literal">INBOX</code>). This is
done in order to avoid having to rewrite the default
system mailbox file "in place", due to restricted
permissions on the spool directory. Updating the
default system mailbox in place may result in
corruption if the process is interrupted while the
update is in progress. Copying mail from the default
system mailbox to <code class="filename">$HOME/Inbox</code> allows safe access to
new messages.</p>
</div>
</dd>
<dt><span class="term">smtp://[<span class="optional"><em class="replaceable"><code>user</code></em>@</span>]<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>Create an account object for sending mail. The
created <span class="structname">mail::account</span>'s
<a class="link" href="mail-getsendfolder.html" title="mail::account::getSendFolder" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getSendFolder</span>(3x)</span></a>
method will create a special <span class="structname">mail::folder</span> object. Adding a
message to this "folder" will E-mail this message via
SMTP.</p>
<p>The colon and <em class="replaceable"><code>port</code></em> are optional;
defaulting to the standard SMTP port 25. Sometimes it
is useful to specify port 587, where the message
submission protocol is available (the message
submission protocol is almost identical to SMTP, with
the most notable difference is that authentication is
required). A slash, followed by a slash-separated list
of <a class="link" href="mail-open.html#mail-open-options" title="Account Options" shape="rect">additional options</a>
may follow.</p>
<p>[<span class="optional">user</span>]@ is optional,
and enables authenticated SMTP. [<span class="optional">user</span>] identifies the authentication
id. [<span class="optional">user</span>] may contain
any characters except <code class="literal">/</code>,
<code class="literal">@</code>, <code class="literal">%</code>, and <code class="literal">:</code>.
These characters may be specified by using <code class="literal">%</code> followed by a two-digit uppercase
hexadecimal ASCII code for the character.</p>
</dd>
<dt><span class="term">smtps://[<span class="optional"><em class="replaceable"><code>user</code></em>@</span>]<em class="replaceable"><code>server[<span class="optional">:port</span>]</code></em>[<span class="optional">/options</span>]</span></dt>
<dd>
<p>Like "smtp", but use encryption to connect to the
SMTP server, and use the default <code class="literal">smtps</code> port (usually 465).</p>
</dd>
<dt><span class="term">sendmail://localhost</span></dt>
<dd>
<p>Like "smtp", but use the local <span class="command"><strong>sendmail</strong></span> command to
send mail.</p>
</dd>
</dl>
</div>
<p>There are several alternative ways to provide a login
passwords for <em class="parameter"><code>url</code></em>s
that require login information. <em class="parameter"><code>pwd</code></em> should be set if the login
password is known in advance. If the login password is not
known, <em class="parameter"><code>loginCallbackObj</code></em> needs to be
initialized to a non-NULL pointer. <em class="parameter"><code>loginCallbackObj</code></em> may be set to
NULL if <em class="parameter"><code>pwd</code></em> specifies
a password.</p>
<p><em class="parameter"><code>certificates</code></em> is a
vector of strings that optionally contain <acronym class="acronym">SSL</acronym> certificates. The application can
optionally authenticate using an <acronym class="acronym">SSL</acronym> instead of a userid/password. Both
the userid/password and SSL certificates may be defined. If
the server does not accept an SSL certificate, the
userid/password gets used as a fallback option.
<acronym class="acronym">SSL</acronym> certificate
authentication is implemented for IMAP and POP3 accounts, and
for SMTP accounts (see the USAGE section).</p>
<p>If defined, the each string in the <em class="parameter"><code>certificates</code></em> array contains a
single string that contains a PEM-formatted SSL certificate
and its corresponding key. The certificate string should
contain a “<span class="quote">-----BEGIN
CERTIFICATE-----</span>” section followed by a
“<span class="quote">-----BEGIN RSA PRIVATE
KEY-----</span>” or a “<span class="quote">-----BEGIN DH PRIVATE KEY-----</span>” section.
If the certificate supplies an intermediate authority
certificate, the additional “<span class="quote">-----BEGIN CERTIFICATE-----</span>” section
follows the key.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Passphrase-protected keys are not supported.</p>
</div>
<p><em class="parameter"><code>certificates</code></em> is a
vector, and multiple certificates may be placed in the
vector. The certificate gets selected from the available
multiple choices based on the peer's acceptable certificate
authorities.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>If more than one certificate is signed by the peer's
certificate authorities, the actual certificate gets chosen
at random.</p>
</div>
<p><em class="parameter"><code>loginCallbackObj</code></em>'s
<code class="function">loginPrompt</code> method will be
invoked to obtain the login password, if one is needed. If
<em class="parameter"><code>url</code></em> does not specify
the login ID either, <code class="function">loginPrompt</code> will be invoked twice: once to
obtain the login ID, the second time to obtain the login
password.</p>
<p>If <em class="parameter"><code>loginCallbackObj</code></em> is not NULL,
the object must not be destroyed until the login request
ultimately succeeds, or fails.</p>
<p>The application's implementation of the <em class="parameter"><code>loginCallbackObj</code></em>'s <code class="function">loginPrompt</code> method obtains the account's
login id or password, and invokes the <code class="function">mail::loginCallback::callback</code> method.
<code class="function">loginPrompt</code> receives two
parameters: <em class="parameter"><code>callbackType</code></em> is either
<code class="literal">USERID</code> or <code class="literal">PASSWORD</code>, and it indicates whether the
application needs to return the login id, or the password;
and a suggested prompt.</p>
<p><code class="function">loginPrompt</code> can call
<code class="function">mail::loginCallback::callbackCancel</code> to
indicate that the login process should be aborted. Note that
the act of invoking <code class="function">callbackCancel</code> does not officially fail the
login request; the application is subsequently notified, in
the usual manner, that the login request failed.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><code class="function">loginPrompt</code> is invoked
from within <span class="application">LibMAIL</span> ; as
such no <span class="application">LibMAIL</span> calls can
be made (except for <code class="function">mail::loginCallback::callback</code> or
<code class="function">mail::loginCallback::callbackCancel</code>).
Note that all <span class="application">LibMAIL</span>
processing is halted until <code class="function">loginPrompt</code> terminates. If the password
is already known, <code class="function">loginPrompt</code>
may invoke <code class="function">mail::loginCallback::callback</code>
immediately. This is also the only option with the
<a class="link" href="synchronous.html" title="mail::ACCOUNT Synchronous API reference" shape="rect">Synchronous API</a>, since <a class="link" href="account-login.html" title="mail::ACCOUNT::login" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::ACCOUNT::login</span>(3x)</span></a>
does not return control to the application until the login
process completes.</p>
<p>Applications that use the asynchronous <a class="link" href="native.html" title="mail::account Native API reference" shape="rect">Native
API</a> have another option. <code class="function">loginPrompt</code> gets invoked by <a class="link" href="mail-process.html" title="mail::account::process" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::process</span>(3x)</span></a>.
<code class="function">loginPrompt</code> may terminate
without invoking <code class="function">mail::loginCallback::callback</code>. The
application may then prompt for the requested information
after <a class="link" href="mail-process.html" title="mail::account::process" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::process</span>(3x)</span></a>
returns, and invoke either <code class="function">mail::loginCallback::callback</code> or
<code class="function">mail::loginCallback::callbackCancel</code>, at
some point later down the road, which will result in the
eventual completion of the login request. Note that the
login request may fail before the application calls
<code class="function">mail::loginCallback::callback</code>
or <code class="function">mail::loginCallback::callbackCancel</code>. This
can occur if the server closed the login connection before
the application supplied the login id or password.</p>
</div>
<div class="refsect2" lang="en" xml:lang="en">
<a id="mail-open-options" shape="rect" name="mail-open-options"> </a>
<h3>Account Options</h3>
<p>The following options may be appended to <em class="parameter"><code>url</code></em> for some account types.
Multiple options may be listed in any order:</p>
<div class="variablelist">
<dl>
<dt><span class="term"><code class="literal">/cram</code></span></dt>
<dd>
<p>Do not open the account unless the server supports
secure password authentication. Secure password
authentication verifies the account's password using
a challenge/response authentication mechanism (where
the label "<code class="literal">cram</code>" comes
from). The actual password is never actually
transmitted to the server, and therefore cannot be
intercepted while in transit over an untrusted
network.</p>
<p>Secure password authentication is not supported by
all servers. This option may not work with some
servers. This option does not enable secure password
authentication, it only mandates its use. If the
server supports secure password authentication, it
will be used even without the <code class="literal">/cram</code> option. Traditional
userid/password authentication will be used only if
the server does not implement secure password
authentication. The <code class="literal">/cram</code> option makes secure password
authentication mandatory.</p>
<p>The <code class="literal">/cram</code> option is
marginally useful even with encrypted server
connections. The secure password authentication never
sends the explicit password to the server. Encryption
makes it theoretically impossible to recover the
password from an encrypted data connection; but with
secure authentication the password is never sent over
the connection in the first place (the password's
validity is certified by exchanging certain
mathematical calculations between the server and the
client). If the server is compromised, the
compromised server will not receive the account
password (unless the password is recovered from the
server in other ways).</p>
</dd>
<dt><span class="term"><code class="literal">/debugio</code></span></dt>
<dd>
<p>Enable a debugging option that logs all network
traffic for this account to standard error.</p>
</dd>
<dt><span class="term"><code class="literal">/imap</code></span></dt>
<dd>
<p>Do not use the <a class="link" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1" shape="rect">SMAP</a> if the server claims the
availability of this experimental mail access
protocol, and fall back to IMAP compatibility mode
(this option is meaningful only with
“<span class="quote"><code class="literal">imap://</code></span>” and
“<span class="quote"><code class="literal">imaps://</code></span>” URLs).</p>
</dd>
<dt><span class="term"><code class="literal">/notls</code></span></dt>
<dd>
<p>Do not upgrade a plain connection to an encrypted
one. This option is primarily used for testing and
debugging purposes. Sometimes this option might be
useful with servers that claim to offer encryption,
but are unable to do so when taken up on their
offer.</p>
</dd>
<dt><span class="term"><code class="literal">/novalidate-cert</code></span></dt>
<dd>
<p>Do not validate the server's SSL certificate when
using an encrypted connection. Normally the mail
server's SSL certificate must be validate when using
an encrypted connection. The certificate's name must
match the server's name, and the certificate must be
signed by a trusted certificate authority.</p>
<p>The encrypted connection normally fails if the
certificate cannot be validate. Validation requires
that a list of trusted certificate authorities must
be known and configured. It's simply impossible to
know which certificate authorities are valid without
an explicit list of valid, known, trusted,
certificate authorities. If a trusted authority list
is not configured, no certificate can be validated.
If the server's certificate is a self-signed
certificate (this is often used for testing
purposes), or if it's not signed by a known
authority, the encrypted connection fails.</p>
<p>This <code class="literal">/novalidate-cert</code>
option disables certificate validation. The encrypted
connection will be established even if the server's
certificate would otherwise be rejected.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>This option is applicable even when an encrypted
IMAP or POP3 connection is not explicitly
requested. Many mail servers are capable of
automatically upgrading unencrypted connections to
a fully-encrypted connection. If a mail server
claims to be able to use encryption, then there's
no reason not to use it. The result is that all
encryption certification requirements still apply
even when encryption is not explicitly
requested.</p>
</div>
</dd>
<dt><span class="term"><code class="literal">/timeout=</code><em class="replaceable"><code>N</code></em></span></dt>
<dd>
<p>Close the connection if the IMAP/SMAP, POP3, or
NNTP server does not respond to a command in
<em class="replaceable"><code>N</code></em> seconds
(default: 60).</p>
</dd>
<dt><span class="term"><code class="literal">/noop=</code><em class="replaceable"><code>N</code></em></span></dt>
<dd>
<p>Check for new messages in the currently open
IMAP/SMAP folder every <em class="replaceable"><code>N</code></em> seconds (default:
600).</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Most IMAP servers implement a protocol extension
that reports new messages (and other changes to the
folder's contents) immediately, without waiting for
an explicit request to check for new mail.</p>
</div>
<p>This option is also used by POP3 folders, where it
defaults to 60 seconds. POP3 does not provide for new
mail notification; the option's only purpose is to
prevent the POP3 server from disconnecting due to
inactivity.</p>
</dd>
<dt><span class="term"><code class="literal">/autologout=</code><em class="replaceable"><code>N</code></em></span></dt>
<dd>
<p>Automatically close an NNTP connection after
<em class="replaceable"><code>N</code></em> seconds
of inactivty (default: 300). The connection will be
automatically reestablished, when necessary.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id594056" shape="rect" name="id594056"> </a>
<h2>RETURN CODES AND CALLBACKS</h2>
<p><code class="function">mail::account::open</code>
allocates and returns a <span class="structname">mail::account</span> object. However, the mail
account may not be fully open, and ready for business. Like
most other functions the application must wait until the
<em class="parameter"><code>callback</code></em>'s
<code class="function">success</code> or <code class="function">fail</code> method is invoked.</p>
<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>
<p><code class="function">mail::account::open</code> returns
a <code class="literal">NULL</code> pointer in the event of
an immediate failure, in addition to invoking the
<code class="function">fail</code> method. <code class="function">mail::account::open</code> may also invoke the
<code class="function">success</code> method before it
returns, however in most cases the <code class="function">success</code> method will be invoked by <a class="link" href="mail-process.html" title="mail::account::process" shape="rect"><code class="function">mail::account::process</code></a>() at a later
time.</p>
<p>The application may not destroy the <em class="parameter"><code>callback</code></em> object until either
method is invoked.</p>
<p>The <em class="parameter"><code>disconnectCallback</code></em>'s
<code class="function">disconnected</code> method will be
invoked whenever the connection to the mail server
terminates. The <code class="function">disconnected</code>
method may or may not be invoked if the initial connection to
the server fails (applications should not rely on either
behavior). The <code class="function">disconnected</code>
method will be invoked when the account is closed even for
account types that do not normally use a network connection
(such as a local mail account).</p>
<p>The <em class="parameter"><code>disconnectCallback</code></em>'s
<code class="function">servererror</code> method may be
invoked at any time, whenever an error is reported by the
server that's not directly caused by the currently requested
mail operation, and the error is not severe enough to result
in a disconnection from the server. <code class="function">servererror</code> should display the error
message in a highly visible manner.</p>
<p>Applications are responsible for destroying <span class="structname">mail::account</span> objects after they are no
longer needed.</p>
<p>The <em class="parameter"><code>disconnectCallback</code></em> object may
not be destroyed until after the <span class="structname">mail::account</span> object is destroyed.</p>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id594325" shape="rect" name="id594325"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="mail-getsendfolder.html" title="mail::account::getSendFolder" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::getSendFolder</span>(3x)</span></a>,
<a class="link" href="mail-isremoteurl.html" title="mail::account::isRemoteUrl" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::isRemoteUrl</span>(3x)</span></a>,
<a class="link" href="mail-loginurlencode.html" title="mail::loginUrlEncode" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::loginUrlEncode</span>(3x)</span></a>,
<a class="link" href="mail-process.html" title="mail::account::process" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::process</span>(3x)</span></a>,
<a class="link" href="mail-readtoplevel.html" title="mail::account::readTopLevelFolders" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::account::readTopLevelFolders</span>(3x)</span></a>,
<a class="link" href="mail-setappcharset.html" title="mail::setAppCharset" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::setAppCharset</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-movemessagesto.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-poll.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">mail::account::moveMessagesTo </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::poll</td>
</tr>
</table>
</div>
</body>
</html>
