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