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