1 Cone©
2MAIL::ACCOUNT::OPEN(3x) Cone: COnsole Newsreader And E MAIL::ACCOUNT::OPEN(3x)
4
8 mail::account::open - Open a new mail account
9
11 #include <libmail/mail.H>
12 class myCallback : public mail::callback {
15 public:
16 void success(std::string msg);
17 void fail(std::string msg);
18 };
19 class myDisconnectCallback : public mail::callback::disconnect {
22 public:
23 void disconnected(const char *msg);
24 void servererror(const char *msg);
25 };
26 #include <libmail/logininfo.H>
28 class myPromptCallback : public mail::loginCallback {
30 public:
31 void loginPrompt(mail::loginCallback::callbackType, std::string);
32 };
33 void myPromptCallback::loginPrompt(mail::loginCallback::callbackType cbType,
35 string prompt)
36 {
37 struct termios ti, ti2;
38 cout << prompt << flush;
40 tcgetattr(0, &ti);
42 ti2=ti;
44 if (cbType == PASSWORD)
46 {
47 ti2.c_lflag &= ~ECHO;
48 tcsetattr(0, TCSAFLUSH, &ti2);
49 }
50 std::string reply;
52 if (getline(cin, reply).fail())
54 {
55 callbackCancel();
56 return;
57 }
58 if (cbType != USERID) // It's PASSWORD
60 tcsetattr(0, TCSAFLUSH, &ti);
61 callback(reply);
63 }
64 mail::account::openInfo accountOpenInfo;
66 myPromptCallback passwdCallback;
67 accountOpenInfo.url="imap://john@imap.example.com/novalidate-cert";
69 accountOpenInfo.pwd="secret";
70 accountOpenInfo.certificates.push_back(pemCertStr);
71 accountOpenInfo.extraString=""; // Used by nntp:, nntps:, pop3maildrop: and pop3maildrops:
72 accountOpenInfo.loginCallbackObj= &passwdCallback;
73 mail::account *account=mail::account::open(accountOpenInfo,
77 myCallback &callback,
78 myDisconnectCallback &disconnectCallback);
79
81 mail::account::open opens a mail account on a server. url identifies
82 the account. url should contain a text string that identifies one of
83 the following types of accounts:
84 imap://user@server[:port][/options]
86 An IMAP[1] or an SMAP account on server. The colon and port are
87 optional; defaulting to the standard IMAP port 143. A slash,
88 followed by a slash-separated list of additional options may
89 follow.
90 user identifies the account login id. user may contain any
92 characters except /, @, %, and :. These characters may be specified
93 by using %, followed by a two-digit uppercase hexadecimal ASCII
94 code for the character.
95 pop3://user@server[:port][/options]
97 A POP3 account on server. The colon and port are optional;
98 defaulting to the standard POP3 port 110. A slash, followed by a
99 slash-separated list of additional options may follow.
100 user identifies the account login id. user may contain any
102 characters except /, @, %, and :. These characters may be specified
103 by using % followed by a two-digit uppercase hexadecimal ASCII code
104 for the character.
105 Note
107 The POP3 server must support the UIDL command, which is
108 implemented by all modern POP3 servers. Some very old POP3
109 servers may not support this command, in which case use a
110 pop3maildrop URL instead.
111 pop3maildrop://user@server[:port][/options]
113 Like “pop3”, except that messages are downloaded, then deleted,
114 from the POP3 server. Use “pop3maildrop” maildrop when the remote
115 server does not implement the UIDL command.
116 extraString must be initialized to the name of a maildir where
118 messages from the POP3 server will be downloaded to. If the maildir
119 does not exist, it will be automatically created.
120 nntp://user@server[:port][/options]
122 Access Usenet newsgroups via nntp on server. The colon and port are
123 optional; defaulting to the standard NNTP port 119. A slash,
124 followed by a slash-separated list of additional options may
125 follow.
126 extraString must be initialized to the name of a file where the
128 list of subscribed newsgroups, and read articles, will be saved.
129 Note
131 LibMAIL uses a slightly expanded version of the traditional
132 .newsrc format, containing some extra header information.
133 user and pwd should be specified if the NNTP server requires
134 authentication. Otherwise these parameters may be omitted.
135 imaps://user@server[:port][/options]
137 Like "imap", but use encryption to connect to the IMAP/SMAP server,
138 and use the default imaps port (usually 993).
139 pop3s://user@server[:port][/options]
141 Like “pop3”, but use encryption to connect to the POP3 server, and
142 use the default pop3s port (usually 995).
143 pop3maildrops://user@server[:port][/options]
145 Like “pop3maildrop”, but use encryption to connect to the POP3
146 server, and use the default pop3s port (usually 995).
147 nntps://user@server[:port][/options]
149 Like "nntp", but use encryption to connect to the NNTP server, and
150 use the default nntps port (usually 563).
151 maildir:[path]
153 Mail in a local maildir. [path] specifies the path to the
154 maildir-type mailbox. [path] may be a relative path, anchored at
155 the home directory (NOT the process's current directory).
156 "maildir:Maildir" is the usual way to open $HOME/Maildir.
157 mail:[path]
159 Open mail in a local mailbox. [path] specifies the path to a file
160 or a directory containing mbox-type mailboxes. [path] may be a
161 relative path, anchored at the home directory (NOT the process's
162 current directory). [path] may refer to a directory, in which case
163 the directory's contents are read as mbox-type folders.
164 "maildir:Mail" is the usual way to open mail in $HOME/Mail.
165 inbox:[path]
167 Open mail in a local mailbox. This is the same as "mail:[path]",
168 with the additional inclusion of the default system mailbox
169 (usually in /var/spool/mail), represented by the special folder
170 named INBOX.
171 Note
173 The default system mailbox is implemented by creating
174 $HOME/Inbox, and automatically copying all mail from the
175 default system mailbox to $HOME/Inbox (which is represented as
176 the INBOX). This is done in order to avoid having to rewrite
177 the default system mailbox file "in place", due to restricted
178 permissions on the spool directory. Updating the default system
179 mailbox in place may result in corruption if the process is
180 interrupted while the update is in progress. Copying mail from
181 the default system mailbox to $HOME/Inbox allows safe access to
182 new messages.
183 smtp://[user@]server[:port][/options]
185 Create an account object for sending mail. The created
186 mail::account's mail::account::getSendFolder(3x) method will create
187 a special mail::folder object. Adding a message to this "folder"
188 will E-mail this message via SMTP.
189 The colon and port are optional; defaulting to the standard SMTP
191 port 25. Sometimes it is useful to specify port 587, where the
192 message submission protocol is available (the message submission
193 protocol is almost identical to SMTP, with the most notable
194 difference is that authentication is required). A slash, followed
195 by a slash-separated list of additional options may follow.
196 [user]@ is optional, and enables authenticated SMTP. [user]
198 identifies the authentication id. [user] may contain any
199 characters except /, @, %, and :. These characters may be specified
200 by using % followed by a two-digit uppercase hexadecimal ASCII code
201 for the character.
202 smtps://[user@]server[:port][/options]
204 Like "smtp", but use encryption to connect to the SMTP server, and
205 use the default smtps port (usually 465).
206 sendmail://localhost
208 Like "smtp", but use the local sendmail command to send mail.
209 There are several alternative ways to provide a login passwords for
211 urls that require login information. pwd should be set if the login
212 password is known in advance. If the login password is not known,
213 loginCallbackObj needs to be initialized to a non-NULL pointer.
214 loginCallbackObj may be set to NULL if pwd specifies a password.
215 certificates is a vector of strings that optionally contain SSL
217 certificates. The application can optionally authenticate using an SSL
218 instead of a userid/password. Both the userid/password and SSL
219 certificates may be defined. If the server does not accept an SSL
220 certificate, the userid/password gets used as a fallback option. SSL
221 certificate authentication is implemented for IMAP and POP3 accounts,
222 and for SMTP accounts (see the USAGE section).
223 If defined, the each string in the certificates array contains a single
225 string that contains a PEM-formatted SSL certificate and its
226 corresponding key. The certificate string should contain a “-----BEGIN
227 CERTIFICATE-----” section followed by a “-----BEGIN RSA PRIVATE
228 KEY-----” or a “-----BEGIN DH PRIVATE KEY-----” section. If the
229 certificate supplies an intermediate authority certificate, the
230 additional “-----BEGIN CERTIFICATE-----” section follows the key.
231 Note
233 Passphrase-protected keys are not supported.
234 certificates is a vector, and multiple certificates may be placed in
236 the vector. The certificate gets selected from the available multiple
237 choices based on the peer's acceptable certificate authorities.
238 Note
240 If more than one certificate is signed by the peer's certificate
241 authorities, the actual certificate gets chosen at random.
242 loginCallbackObj's loginPrompt method will be invoked to obtain the
244 login password, if one is needed. If url does not specify the login ID
245 either, loginPrompt will be invoked twice: once to obtain the login ID,
246 the second time to obtain the login password.
247 If loginCallbackObj is not NULL, the object must not be destroyed until
249 the login request ultimately succeeds, or fails.
250 The application's implementation of the loginCallbackObj's loginPrompt
252 method obtains the account's login id or password, and invokes the
253 mail::loginCallback::callback method. loginPrompt receives two
254 parameters: callbackType is either USERID or PASSWORD, and it indicates
255 whether the application needs to return the login id, or the password;
256 and a suggested prompt.
257 loginPrompt can call mail::loginCallback::callbackCancel to indicate
259 that the login process should be aborted. Note that the act of invoking
260 callbackCancel does not officially fail the login request; the
261 application is subsequently notified, in the usual manner, that the
262 login request failed.
263 Note
265 loginPrompt is invoked from within LibMAIL ; as such no LibMAIL
266 calls can be made (except for mail::loginCallback::callback or
267 mail::loginCallback::callbackCancel). Note that all LibMAIL
268 processing is halted until loginPrompt terminates. If the password
269 is already known, loginPrompt may invoke
270 mail::loginCallback::callback immediately. This is also the only
271 option with the Synchronous API, since mail::ACCOUNT::login(3x)
272 does not return control to the application until the login process
273 completes.
274 Applications that use the asynchronous Native API have another
276 option. loginPrompt gets invoked by mail::account::process(3x).
277 loginPrompt may terminate without invoking
278 mail::loginCallback::callback. The application may then prompt for
279 the requested information after mail::account::process(3x) returns,
280 and invoke either mail::loginCallback::callback or
281 mail::loginCallback::callbackCancel, at some point later down the
282 road, which will result in the eventual completion of the login
283 request. Note that the login request may fail before the
284 application calls mail::loginCallback::callback or
285 mail::loginCallback::callbackCancel. This can occur if the server
286 closed the login connection before the application supplied the
287 login id or password.
288 Account Options
290 The following options may be appended to url for some account types.
291 Multiple options may be listed in any order:
292 /cram
294 Do not open the account unless the server supports secure password
295 authentication. Secure password authentication verifies the
296 account's password using a challenge/response authentication
297 mechanism (where the label "cram" comes from). The actual password
298 is never actually transmitted to the server, and therefore cannot
299 be intercepted while in transit over an untrusted network.
300 Secure password authentication is not supported by all servers.
302 This option may not work with some servers. This option does not
303 enable secure password authentication, it only mandates its use. If
304 the server supports secure password authentication, it will be used
305 even without the /cram option. Traditional userid/password
306 authentication will be used only if the server does not implement
307 secure password authentication. The /cram option makes secure
308 password authentication mandatory.
309 The /cram option is marginally useful even with encrypted server
311 connections. The secure password authentication never sends the
312 explicit password to the server. Encryption makes it theoretically
313 impossible to recover the password from an encrypted data
314 connection; but with secure authentication the password is never
315 sent over the connection in the first place (the password's
316 validity is certified by exchanging certain mathematical
317 calculations between the server and the client). If the server is
318 compromised, the compromised server will not receive the account
319 password (unless the password is recovered from the server in other
320 ways).
321 /debugio
323 Enable a debugging option that logs all network traffic for this
324 account to standard error.
325 /imap
327 Do not use the SMAP if the server claims the availability of this
328 experimental mail access protocol, and fall back to IMAP
329 compatibility mode (this option is meaningful only with “imap://”
330 and “imaps://” URLs).
331 /notls
333 Do not upgrade a plain connection to an encrypted one. This option
334 is primarily used for testing and debugging purposes. Sometimes
335 this option might be useful with servers that claim to offer
336 encryption, but are unable to do so when taken up on their offer.
337 /novalidate-cert
339 Do not validate the server's SSL certificate when using an
340 encrypted connection. Normally the mail server's SSL certificate
341 must be validate when using an encrypted connection. The
342 certificate's name must match the server's name, and the
343 certificate must be signed by a trusted certificate authority.
344 The encrypted connection normally fails if the certificate cannot
346 be validate. Validation requires that a list of trusted certificate
347 authorities must be known and configured. It's simply impossible to
348 know which certificate authorities are valid without an explicit
349 list of valid, known, trusted, certificate authorities. If a
350 trusted authority list is not configured, no certificate can be
351 validated. If the server's certificate is a self-signed certificate
352 (this is often used for testing purposes), or if it's not signed by
353 a known authority, the encrypted connection fails.
354 This /novalidate-cert option disables certificate validation. The
356 encrypted connection will be established even if the server's
357 certificate would otherwise be rejected.
358 Note
360 This option is applicable even when an encrypted IMAP or POP3
361 connection is not explicitly requested. Many mail servers are
362 capable of automatically upgrading unencrypted connections to a
363 fully-encrypted connection. If a mail server claims to be able
364 to use encryption, then there's no reason not to use it. The
365 result is that all encryption certification requirements still
366 apply even when encryption is not explicitly requested.
367 /timeout=N
369 Close the connection if the IMAP/SMAP, POP3, or NNTP server does
370 not respond to a command in N seconds (default: 60).
371 /noop=N
373 Check for new messages in the currently open IMAP/SMAP folder every
374 N seconds (default: 600).
375 Note
377 Most IMAP servers implement a protocol extension that reports
378 new messages (and other changes to the folder's contents)
379 immediately, without waiting for an explicit request to check
380 for new mail.
381 This option is also used by POP3 folders, where it defaults to 60
382 seconds. POP3 does not provide for new mail notification; the
383 option's only purpose is to prevent the POP3 server from
384 disconnecting due to inactivity.
385 /autologout=N
387 Automatically close an NNTP connection after N seconds of inactivty
388 (default: 300). The connection will be automatically reestablished,
389 when necessary.
390
392 mail::account::open allocates and returns a mail::account object.
393 However, the mail account may not be fully open, and ready for
394 business. Like most other functions the application must wait until the
395 callback's success or fail method is invoked.
396 The application must wait until callback's success or fail method is
398 invoked. The success method is invoked when this request is succesfully
399 processed. The fail method is invoked if this request cannot be
400 processed. The application must not destroy callback until either the
401 success or fail method is invoked.
402 Note
404 callback's fail method may be invoked even after other callback
405 methods were invoked. This indicates that the request was partially
406 completed before the error was encountered.
407 mail::account::open returns a NULL pointer in the event of an immediate
409 failure, in addition to invoking the fail method. mail::account::open
410 may also invoke the success method before it returns, however in most
411 cases the success method will be invoked by mail::account::process() at
412 a later time.
413 The application may not destroy the callback object until either method
415 is invoked.
416 The disconnectCallback's disconnected method will be invoked whenever
418 the connection to the mail server terminates. The disconnected method
419 may or may not be invoked if the initial connection to the server fails
420 (applications should not rely on either behavior). The disconnected
421 method will be invoked when the account is closed even for account
422 types that do not normally use a network connection (such as a local
423 mail account).
424 The disconnectCallback's servererror method may be invoked at any time,
426 whenever an error is reported by the server that's not directly caused
427 by the currently requested mail operation, and the error is not severe
428 enough to result in a disconnection from the server. servererror
429 should display the error message in a highly visible manner.
430 Applications are responsible for destroying mail::account objects after
432 they are no longer needed.
433 The disconnectCallback object may not be destroyed until after the
435 mail::account object is destroyed.
436
438 mail::account::getSendFolder(3x), mail::account::isRemoteUrl(3x),
439 mail::loginUrlEncode(3x), mail::account::process(3x),
440 mail::account::readTopLevelFolders(3x), mail::setAppCharset(3x).
441
443 Sam Varshavchik
444
446 1. IMAP
447 http://www.rfc-editor.org/rfc/rfc3501.txt
448Cone© 08/25/2016 MAIL::ACCOUNT::OPEN(3x)