mail::account::open — Open a new mail account
#include <libmail/mail.H>
class myCallback : public mail::callback {
public:
void success(std::string msg);
void fail(std::string msg);
};
class myDisconnectCallback : public mail::callback::disconnect {
public:
void disconnected(const char *msg);
void servererror(const char *msg);
};
#include <libmail/logininfo.H>
class myPromptCallback : public mail::loginCallback {
public:
void loginPrompt(mail::loginCallback::callbackType, std::string);
};
void myPromptCallback::loginPrompt(mail::loginCallback::callbackType cbType,
string prompt)
{
struct termios ti, ti2;
cout << prompt << flush;
tcgetattr(0, &ti);
ti2=ti;
if (cbType == PASSWORD)
{
ti2.c_lflag &= ~ECHO;
tcsetattr(0, TCSAFLUSH, &ti2);
}
std::string reply;
if (getline(cin, reply).fail())
{
callbackCancel();
return;
}
if (cbType != USERID) // It's PASSWORD
tcsetattr(0, TCSAFLUSH, &ti);
callback(reply);
}
mail::account::openInfo accountOpenInfo;
myPromptCallback passwdCallback;
accountOpenInfo.url="imap://john@imap.example.com/novalidate-cert";
accountOpenInfo.pwd="secret";
accountOpenInfo.certificates.push_back(pemCertStr);
accountOpenInfo.extraString=""; // Used by nntp:, nntps:, pop3maildrop: and pop3maildrops:
accountOpenInfo.loginCallbackObj= &passwdCallback;
mail::account *account=mail::account::open( |
accountOpenInfo, |
| myCallback &callback, | |
myDisconnectCallback
&disconnectCallback); |
mail::account::open opens a
mail account on a server. url identifies the account.
url should contain a
text string that identifies one of the following types of
accounts:
user@server[:port][/options]An IMAP or an SMAP account on server. The colon and
port are
optional; defaulting to the standard IMAP port 143. A
slash, followed by a slash-separated list of additional options
may follow.
user
identifies the account login id. user may contain any
characters except /,
@, %, and :.
These characters may be specified by using %, followed by a two-digit uppercase
hexadecimal ASCII code for the character.
user@server[:port][/options]A POP3 account on server. The colon and
port are
optional; defaulting to the standard POP3 port 110. A
slash, followed by a slash-separated list of additional options
may follow.
user
identifies the account login id. user may contain any
characters except /,
@, %, and :.
These characters may be specified by using % followed by a two-digit uppercase
hexadecimal ASCII code for the character.
The POP3 server must support the UIDL command, which is implemented
by all modern POP3 servers. Some very old POP3
servers may not support this command, in which case
use a pop3maildrop URL
instead.
user@server[:port][/options]Like “pop3”, except that messages are
downloaded, then deleted, from the POP3 server. Use
“pop3maildrop” maildrop when the
remote server does not implement the UIDL command.
extraString
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.
user@server[:port][/options]Access Usenet newsgroups via nntp on server. The colon and
port are
optional; defaulting to the standard NNTP port 119. A
slash, followed by a slash-separated list of additional options
may follow.
extraString
must be initialized to the name of a file where the
list of subscribed newsgroups, and read articles, will
be saved.
LibMAIL uses a
slightly expanded version of the traditional
.newsrc format,
containing some extra header information.
user and
pwd should be
specified if the NNTP server requires authentication.
Otherwise these parameters may be omitted.
user@server[:port][/options]Like "imap", but use encryption to connect to the
IMAP/SMAP server, and use the default imaps port (usually 993).
user@server[:port][/options]Like “pop3”, but use encryption to
connect to the POP3 server, and use the default
pop3s port (usually
995).
user@server[:port][/options]Like “pop3maildrop”, but use encryption
to connect to the POP3 server, and use the default
pop3s port (usually
995).
user@server[:port][/options]Like "nntp", but use encryption to connect to the
NNTP server, and use the default nntps port (usually 563).
Mail in a local maildir. [path] specifies the path to the
maildir-type mailbox. [path] may be a relative path,
anchored at the home directory (NOT the process's
current directory). "maildir:Maildir" is the usual way to
open $HOME/Maildir.
Open mail in a local mailbox. [path] specifies the path to a file or
a directory containing mbox-type mailboxes.
[path] may be a relative
path, anchored at the home directory (NOT the process's
current directory). [path] may refer to a directory, in
which case the directory's contents are read as
mbox-type folders. "maildir:Mail" is the usual way to
open mail in $HOME/Mail.
Open mail in a local mailbox. This is the same as
"mail:[path]", with the additional
inclusion of the default system mailbox (usually in
/var/spool/mail),
represented by the special folder named INBOX.
The default system mailbox is implemented by
creating $HOME/Inbox,
and automatically copying all mail from the default
system mailbox to $HOME/Inbox (which is represented
as the INBOX). 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 $HOME/Inbox allows safe access to
new messages.
user@]server[:port][/options]Create an account object for sending mail. The created mail::account's mail::account::getSendFolder(3x) method will create a special mail::folder object. Adding a message to this "folder" will E-mail this message via SMTP.
The colon and port 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 additional options
may follow.
[user]@ is optional,
and enables authenticated SMTP. [user] identifies the authentication
id. [user] may contain
any characters except /,
@, %, and :.
These characters may be specified by using % followed by a two-digit uppercase
hexadecimal ASCII code for the character.
user@]server[:port][/options]Like "smtp", but use encryption to connect to the
SMTP server, and use the default smtps port (usually 465).
Like "smtp", but use the local sendmail command to send mail.
There are several alternative ways to provide a login
passwords for urls
that require login information. pwd should be set if the login
password is known in advance. If the login password is not
known, loginCallbackObj needs to be
initialized to a non-NULL pointer. loginCallbackObj may be set to
NULL if pwd specifies
a password.
certificates is a
vector of strings that optionally contain SSL certificates. The application can
optionally authenticate using an SSL 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.
SSL certificate
authentication is implemented for IMAP and POP3 accounts, and
for SMTP accounts (see the USAGE section).
If defined, the each string in the certificates array contains a
single string that contains a PEM-formatted SSL certificate
and its corresponding key. The certificate string should
contain a “-----BEGIN
CERTIFICATE-----” section followed by a
“-----BEGIN RSA
PRIVATE KEY-----” or a “-----BEGIN DH PRIVATE
KEY-----” section. If the certificate supplies
an intermediate authority certificate, the additional
“-----BEGIN
CERTIFICATE-----” section follows the key.
Passphrase-protected keys are not supported.
certificates 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.
If more than one certificate is signed by the peer's certificate authorities, the actual certificate gets chosen at random.
loginCallbackObj's
loginPrompt method will be
invoked to obtain the login password, if one is needed. If
url does not specify
the login ID either, loginPrompt will be invoked twice: once to
obtain the login ID, the second time to obtain the login
password.
If loginCallbackObj is not NULL,
the object must not be destroyed until the login request
ultimately succeeds, or fails.
The application's implementation of the loginCallbackObj's loginPrompt method obtains the account's
login id or password, and invokes the mail::loginCallback::callback method.
loginPrompt receives two
parameters: callbackType is either
USERID or PASSWORD, and it indicates whether the
application needs to return the login id, or the password;
and a suggested prompt.
loginPrompt can call
mail::loginCallback::callbackCancel to
indicate that the login process should be aborted. Note that
the act of invoking callbackCancel does not officially fail the
login request; the application is subsequently notified, in
the usual manner, that the login request failed.
loginPrompt is invoked
from within LibMAIL ; as
such no LibMAIL calls can
be made (except for mail::loginCallback::callback or
mail::loginCallback::callbackCancel).
Note that all LibMAIL
processing is halted until loginPrompt terminates. If the password
is already known, loginPrompt
may invoke mail::loginCallback::callback
immediately. This is also the only option with the
Synchronous API, since mail::ACCOUNT::login(3x)
does not return control to the application until the login
process completes.
Applications that use the asynchronous Native
API have another option. loginPrompt gets invoked by mail::account::process(3x).
loginPrompt may terminate
without invoking mail::loginCallback::callback. The
application may then prompt for the requested information
after mail::account::process(3x)
returns, and invoke either mail::loginCallback::callback or
mail::loginCallback::callbackCancel, 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
mail::loginCallback::callback
or mail::loginCallback::callbackCancel. This
can occur if the server closed the login connection before
the application supplied the login id or password.
The following options may be appended to url for some account types.
Multiple options may be listed in any order:
/cramDo 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 "cram" comes
from). The actual password is never actually
transmitted to the server, and therefore cannot be
intercepted while in transit over an untrusted
network.
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 /cram option. Traditional
userid/password authentication will be used only if
the server does not implement secure password
authentication. The /cram option makes secure password
authentication mandatory.
The /cram 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).
/debugioEnable a debugging option that logs all network traffic for this account to standard error.
/imapDo not use the SMAP 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 “imap://” and
“imaps://” URLs).
/notlsDo 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.
/novalidate-certDo 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.
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.
This /novalidate-cert
option disables certificate validation. The encrypted
connection will be established even if the server's
certificate would otherwise be rejected.
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.
/timeout=NClose the connection if the IMAP/SMAP, POP3, or
NNTP server does not respond to a command in
N seconds
(default: 60).
/noop=NCheck for new messages in the currently open
IMAP/SMAP folder every N seconds (default:
600).
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.
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.
/autologout=NAutomatically close an NNTP connection after
N seconds
of inactivty (default: 300). The connection will be
automatically reestablished, when necessary.
mail::account::open
allocates and returns a mail::account object. However, the mail
account may not be fully open, and ready for business. Like
most other functions the application must wait until the
callback's
success or fail method is invoked.
The application must wait until callback's success or fail method is invoked. The success method is invoked when this request
is succesfully processed. The fail method is invoked if this request
cannot be processed. The application must not destroy
callback until either
the success or fail method is invoked.
callback's
fail method may be invoked
even after other callback methods were invoked. This
indicates that the request was partially completed before
the error was encountered.
mail::account::open returns
a NULL pointer in the event of
an immediate failure, in addition to invoking the
fail method. mail::account::open may also invoke the
success method before it
returns, however in most cases the success method will be invoked by mail::account::process() at a later
time.
The application may not destroy the callback object until either
method is invoked.
The disconnectCallback's
disconnected method will be
invoked whenever the connection to the mail server
terminates. The disconnected
method may or may not be invoked if the initial connection to
the server fails (applications should not rely on either
behavior). The disconnected
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).
The disconnectCallback's
servererror 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. servererror should display the error
message in a highly visible manner.
Applications are responsible for destroying mail::account objects after they are no longer needed.
The disconnectCallback object may
not be destroyed until after the mail::account object is destroyed.