1MAIL::ACCOUNT::OPEN(3x)mail::account Native API referenceMAIL::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.extraString=""; // Used by nntp:, nntps:, pop3maildrop: and pop3maildrops:
69 accountOpenInfo.loginCallbackObj= &passwdCallback;
70 mail::account *account=mail::account::open (accountOpenInfo, myCallback
75 &callback, myDisconnectCallback &disconnectCallback);
76
78 mail::account::open opens a mail account on a server. url identifies
79 the account. url should contain a text string that identifies one of
80 the following types of accounts:
81 imap://user@server[:port][/options]
83 An IMAP or an SMAP account on server. The colon and port are
84 optional; defaulting to the standard IMAP port 143. A slash,
85 followed by a slash-separated list of additional options may
86 follow.
87 user identifies the account login id. user may contain any
89 characters except /, @, %, and :. These characters may be spec‐
90 ified by using %, followed by a two-digit uppercase hexadecimal
91 ASCII code for the character.
92 pop3://user@server[:port][/options]
94 A POP3 account on server. The colon and port are optional;
95 defaulting to the standard POP3 port 110. A slash, followed by
96 a slash-separated list of additional options may follow.
97 user identifies the account login id. user may contain any
99 characters except /, @, %, and :. These characters may be spec‐
100 ified by using % followed by a two-digit uppercase hexadecimal
101 ASCII code for the character.
102 Note: The POP3 server must support the UIDL command, which is
104 implemented by all modern POP3 servers. Some very old POP3
105 servers may not support this command, in which case use a
106 pop3maildrop URL instead.
107 pop3maildrop://user@server[:port][/options]
109 Like ``pop3'', except that messages are downloaded, then
110 deleted, from the POP3 server. Use ``pop3maildrop'' maildrop
111 when the remote server does not implement the UIDL command.
112 extraString must be initialized to the name of a maildir where
114 messages from the POP3 server will be downloaded to. If the
115 maildir does not exist, it will be automatically created.
116 nntp://user@server[:port][/options]
118 Access Usenet newsgroups via nntp on server. The colon and port
119 are optional; defaulting to the standard NNTP port 119. A
120 slash, followed by a slash-separated list of additional options
121 may follow.
122 extraString must be initialized to the name of a file where the
124 list of subscribed newsgroups, and read articles, will be saved.
125 Note: LibMAIL uses a slightly expanded version of the tradi‐
127 tional .newsrc format, containing some extra header information.
128 user and pwd should be specified if the NNTP server requires authenti‐
130 cation. Otherwise these parameters may be omitted.
131 imaps://user@server[:port][/options]
133 Like "imap", but use encryption to connect to the IMAP/SMAP
134 server, and use the default imaps port (usually 993).
135 pop3s://user@server[:port][/options]
137 Like ``pop3'', but use encryption to connect to the POP3 server,
138 and use the default pop3s port (usually 995).
139 pop3maildrops://user@server[:port][/options]
141 Like ``pop3maildrop'', but use encryption to connect to the POP3
142 server, and use the default pop3s port (usually 995).
143 nntps://user@server[:port][/options]
145 Like "nntp", but use encryption to connect to the NNTP server,
146 and use the default nntps port (usually 563).
147 maildir:[path]
149 Mail in a local maildir. [path] specifies the path to the
150 maildir-type mailbox. [path] may be a relative path, anchored
151 at the home directory (NOT the process's current directory).
152 "maildir:Maildir" is the usual way to open $HOME/Maildir.
153 mail:[path]
155 Open mail in a local mailbox. [path] specifies the path to a
156 file or a directory containing mbox-type mailboxes. [path] may
157 be a relative path, anchored at the home directory (NOT the
158 process's current directory). [path] may refer to a directory,
159 in which case the directory's contents are read as mbox-type
160 folders. "maildir:Mail" is the usual way to open mail in
161 $HOME/Mail.
162 inbox:[path]
164 Open mail in a local mailbox. This is the same as
165 "mail:[path]", with the additional inclusion of the default sys‐
166 tem mailbox (usually in /var/spool/mail), represented by the
167 special folder named INBOX.
168 Note: The default system mailbox is implemented by creating
170 $HOME/Inbox, and automatically copying all mail from the default
171 system mailbox to $HOME/Inbox (which is represented as the
172 INBOX). This is done in order to avoid having to rewrite the
173 default system mailbox file "in place", due to restricted per‐
174 missions on the spool directory. Updating the default system
175 mailbox in place may result in corruption if the process is
176 interrupted while the update is in progress. Copying mail from
177 the default system mailbox to $HOME/Inbox allows safe access to
178 new messages.
179 smtp://[user@]server[:port][/options]
181 Create an account object for sending mail. The created
182 mail::account's mail::account::getSendFolder(3x) method will
183 create a special mail::folder object. Adding a message to this
184 "folder" will E-mail this message via SMTP.
185 The colon and port are optional; defaulting to the standard SMTP
187 port 25. Sometimes it is useful to specify port 587, where the
188 message submission protocol is available (the message submission
189 protocol is almost identical to SMTP, with the most notable dif‐
190 ference is that authentication is required). A slash, followed
191 by a slash-separated list of additional options may follow.
192 [user]@ is optional, and enables authenticated SMTP. [user]
194 identifies the authentication id. [user] may contain any char‐
195 acters except /, @, %, and :. These characters may be specified
196 by using % followed by a two-digit uppercase hexadecimal ASCII
197 code for the character.
198 smtps://[user@]server[:port][/options]
200 Like "smtp", but use encryption to connect to the SMTP server,
201 and use the default smtps port (usually 465).
202 sendmail://localhost
204 Like "smtp", but use the local sendmail command to send mail.
205 There are several alternative ways to provide a login passwords for
207 urls that require login information. pwd should be set if the login
208 password is known in advance. If the login password is not known,
209 loginCallbackObj needs to be initialized to a non-NULL pointer. login‐
210 CallbackObj may be set to NULL if pwd specifies a password.
211 loginCallbackObj's loginPrompt method will be invoked to obtain the
213 login password, if one is needed. If url does not specify the login ID
214 either, loginPrompt will be invoked twice: once to obtain the login ID,
215 the second time to obtain the login password.
216 If loginCallbackObj is not NULL, the object must not be destroyed until
218 the login request ultimately succeeds, or fails.
219 The application's implementation of the loginCallbackObj's loginPrompt
221 method obtains the account's login id or password, and invokes the
222 mail::loginCallback::callback method. loginPrompt receives two parame‐
223 ters: callbackType is either USERID or PASSWORD, and it indicates
224 whether the application needs to return the login id, or the password;
225 and a suggested prompt.
226 loginPrompt can call mail::loginCallback::callbackCancel to indicate
228 that the login process should be aborted. Note that the act of invok‐
229 ing callbackCancel does not officially fail the login request; the
230 application is subsequently notified, in the usual manner, that the
231 login request failed.
232 Note:
234 loginPrompt is invoked from within LibMAIL ; as such no LibMAIL
236 calls can be made (except for mail::loginCallback::callback or
237 mail::loginCallback::callbackCancel). Note that all LibMAIL
238 processing is halted until loginPrompt terminates. If the pass‐
239 word is already known, loginPrompt may invoke mail::loginCall‐
240 back::callback immediately. This is also the only option with
241 the Synchronous API, since mail::ACCOUNT::login(3x) does not
242 return control to the application until the login process com‐
243 pletes.
244 Applications that use the asynchronous Native API have another
246 option. loginPrompt gets invoked by mail::account::process(3x).
247 loginPrompt may terminate without invoking mail::loginCall‐
248 back::callback. The application may then prompt for the
249 requested information after mail::account::process(3x) returns,
250 and invoke either mail::loginCallback::callback or mail::login‐
251 Callback::callbackCancel, at some point later down the road,
252 which will result in the eventual completion of the login
253 request. Note that the login request may fail before the appli‐
254 cation calls mail::loginCallback::callback or mail::loginCall‐
255 back::callbackCancel. This can occur if the server closed the
256 login connection before the application supplied the login id or
257 password.
258 ACCOUNT OPTIONS
260 The following options may be appended to url for some account types.
261 Multiple options may be listed in any order:
262 /cram Do not open the account unless the server supports secure pass‐
264 word authentication. Secure password authentication verifies
265 the account's password using a challenge/response authentication
266 mechanism (where the label "cram" comes from). The actual pass‐
267 word is never actually transmitted to the server, and therefore
268 cannot be intercepted while in transit over an untrusted net‐
269 work.
270 Secure password authentication is not supported by all servers.
272 This option may not work with some servers. This option does
273 not enable secure password authentication, it only mandates its
274 use. If the server supports secure password authentication, it
275 will be used even without the /cram option. Traditional
276 userid/password authentication will be used only if the server
277 does not implement secure password authentication. The /cram
278 option makes secure password authentication mandatory.
279 The /cram option is marginally useful even with encrypted server
281 connections. The secure password authentication never sends the
282 explicit password to the server. Encryption makes it theoreti‐
283 cally impossible to recover the password from an encrypted data
284 connection; but with secure authentication the password is never
285 sent over the connection in the first place (the password's
286 validity is certified by exchanging certain mathematical calcu‐
287 lations between the server and the client). If the server is
288 compromised, the compromised server will not receive the account
289 password (unless the password is recovered from the server in
290 other ways).
291 /debugio
293 Enable a debugging option that logs all network traffic for this
294 account to standard error.
295 /imap Do not use the SMAP if the server claims the availability of
297 this experimental mail access protocol, and fall back to IMAP
298 compatibility mode (this option is meaningful only with
299 ``imap://'' and ``imaps://'' URLs).
300 /nossl Do not upgrade a plain connection to an encrypted one. This
302 option is primarily used for testing and debugging purposes.
303 Sometimes this option might be useful with servers that claim to
304 offer encryption, but are unable to do so when taken up on their
305 offer.
306 /novalidate-cert
308 Do not validate the server's SSL certificate when using an
309 encrypted connection. Normally the mail server's SSL certifi‐
310 cate must be validate when using an encrypted connection. The
311 certificate's name must match the server's name, and the cer‐
312 tificate must be signed by a trusted certificate authority.
313 The encrypted connection normally fails if the certificate can‐
315 not be validate. Validation requires that a list of trusted
316 certificate authorities must be known and configured. It's sim‐
317 ply impossible to know which certificate authorities are valid
318 without an explicit list of valid, known, trusted, certificate
319 authorities. If a trusted authority list is not configured, no
320 certificate can be validated. If the server's certificate is a
321 self-signed certificate (this is often used for testing pur‐
322 poses), or if it's not signed by a known authority, the
323 encrypted connection fails.
324 This /novalidate-cert option disables certificate validation.
326 The encrypted connection will be established even if the
327 server's certificate would otherwise be rejected.
328 Note: This option is applicable even when an encrypted IMAP or
330 POP3 connection is not explicitly requested. Many mail servers
331 are capable of automatically upgrading unencrypted connections
332 to a fully-encrypted connection. If a mail server claims to be
333 able to use encryption, then there's no reason not to use it.
334 The result is that all encryption certification requirements
335 still apply even when encryption is not explicitly requested.
336 /timeout=N
338 Close the connection if the IMAP/SMAP, POP3, or NNTP server does
339 not respond to a command in N seconds (default: 60).
340 /noop=N
342 Check for new messages in the currently open IMAP/SMAP folder
343 every N seconds (default: 600).
344 Note: Most IMAP servers implement a protocol extension that
346 reports new messages (and other changes to the folder's con‐
347 tents) immediately, without waiting for an explicit request to
348 check for new mail.
349 This option is also used by POP3 folders, where it defaults to 60 sec‐
351 onds. POP3 does not provide for new mail notification; the option's
352 only purpose is to prevent the POP3 server from disconnecting due to
353 inactivity.
354 /autologout=N
356 Automatically close an NNTP connection after N seconds of inac‐
357 tivty (default: 300). The connection will be automatically
358 reestablished, when necessary.
359
361 mail::account::open allocates and returns a mail::account object. How‐
362 ever, the mail account may not be fully open, and ready for business.
363 Like most other functions the application must wait until the call‐
364 back's success or fail method is invoked.
365 The application must wait until callback's success or fail method is
367 invoked. The success method is invoked when this request is succes‐
368 fully processed. The fail method is invoked if this request cannot be
369 processed. The application must not destroy callback until either the
370 success or fail method is invoked.
371 Note: callback's fail method may be invoked even after other
373 callback methods were invoked. This indicates that the request
374 was partially completed before the error was encountered.
375 mail::account::open returns a NULL pointer in the event of an immediate
377 failure, in addition to invoking the fail method. mail::account::open
378 may also invoke the success method before it returns, however in most
379 cases the success method will be invoked by mail::account::process() at
380 a later time.
381 The application may not destroy the callback object until either method
383 is invoked.
384 The disconnectCallback's disconnected method will be invoked whenever
386 the connection to the mail server terminates. The disconnected method
387 may or may not be invoked if the initial connection to the server fails
388 (applications should not rely on either behavior). The disconnected
389 method will be invoked when the account is closed even for account
390 types that do not normally use a network connection (such as a local
391 mail account).
392 The disconnectCallback's servererror method may be invoked at any time,
394 whenever an error is reported by the server that's not directly caused
395 by the currently requested mail operation, and the error is not severe
396 enough to result in a disconnection from the server. servererror
397 should display the error message in a highly visible manner.
398 Applications are responsible for destroying mail::account objects after
400 they are no longer needed.
401 The disconnectCallback object may not be destroyed until after the
403 mail::account object is destroyed.
404
406 mail::account::getSendFolder(3x), mail::account::isRemoteUrl(3x),
407 mail::loginUrlEncode(3x), mail::account::process(3x),
408 mail::account::readTopLevelFolders(3x), mail::setAppCharset(3x).
409 10 April 2006 MAIL::ACCOUNT::OPEN(3x)