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.