Qore Pop3Client Module Reference  1.2
 All Classes Namespaces Functions Variables Groups Pages
Pop3Client.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file Pop3Client.qm POP3 client module definition
3 
4 /* Pop3Client.qm Copyright 2013 David Nichols
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
25 // minimum qore version
26 
27 // need mime definitions
28 
29 // need MailMessage classes
30 
31 
32 /* Version History
33  * 2013-05-22 v1.2: David Nichols <david@qore.org>
34  + uncommented the "connected" debug message
35 
36  * 2012-11-03 v1.1: David Nichols <david@qore.org>
37  + added the logPassword() methods and masked password by default in the debug log
38 
39  * 2012-09-04 v1.0: David Nichols <david@qore.org>
40  + doc updates only
41 
42  * 2012-06-12 v1.0: David Nichols <david@qore.org>
43  + initial release
44 
45  based on:
46  - http://tools.ietf.org/html/rfc1939 (POP3)
47 */
48 
82 
83 
89 namespace Pop3Client {
91  const DefaultReadTimeout = 15s;
92 
94  const DefaultConnectTimeout = 30s;
95 
97 
110  class Pop3Client {
111 
112 public:
114  private :
115  Socket sock();
116 
117  // connect string
118  string connect;
119 
120  // ensures exclusive access to the object
121  Mutex mutex();
122 
123  // optional info log closure
124  *code log_info;
125 
126  // optional debug log closure
127  *code log_debug;
128 
129  // "tls" flag
130  bool tls = False;
131 
132  // "starttls" flag
133  bool starttls = False;
134 
135  // "noquit" flag
136  bool noquit = False;
137 
138  // authentication credentials
139  string user;
140  string pass;
141 
142  // logged in flag
143  bool logged_in = False;
144 
145  // read timeout in milliseconds
146  timeout readTimeout = DefaultReadTimeout;
147 
148  // connect timeout in milliseconds
149  timeout connectTimeout = DefaultConnectTimeout;
150 
151  // log password
152  bool log_pass = False;
153 
154  const MaxDebugLine = 2048;
155 
156 public:
158 
159  public :
161  const POP3Port = 110;
162 
164  const POP3SPort = 995;
165 
167  const Protocols = (
168  "pop3": ("tls": False, "port": POP3Port),
169  "pop3s": ("tls": True, "port": POP3SPort),
170  );
171 
172 public:
173 
175 
192  constructor(string url, *code log, *code dbglog);
193 
194 
196 
198  destructor();
199 
200 
202 
209  logPassword(bool pwd);
210 
211 
213 
219  bool logPassword();
220 
221 
223 
230  tls(bool tls);
231 
232 
234 
240  bool tls();
241 
242 
244 
251  starttls(bool starttls);
252 
253 
255 
261  bool starttls();
262 
263 
265 
272  noquit(bool noquit);
273 
274 
276 
285  bool noquit();
286 
287 
289 
301  connect();
302 
303 
305 
316  *hash getMail();
317 
318 
320 
335  hash stat();
336 
337 
339 
354  *hash list();
355 
356 
358 
369  del(softstring msg);
370 
371 
373 
382  del(list l);
383 
384 
386 
395  noop();
396 
397 
399 
408  reset();
409 
410 
412 
418  bool isConnected();
419 
420 
422 
427  disconnect();
428 
429 
431 
436  setReadTimeout(timeout to);
437 
438 
440 
445  int getReadTimeoutMs();
446 
447 
449 
455 
456 
458 
463  setConnectTimeout(timeout to);
464 
465 
467 
472  int getConnectTimeoutMs();
473 
474 
476 
482 
483 
485 
492  forceDisconnect();
493 
494 
496  // don't reimplement this method; fix/enhance it in the module
497 
498 private:
499  final disconnectIntern();
500 public:
501 
502 
503  // don't reimplement this method; fix/enhance it in the module
504 
505 private:
506  final MailMessage::Message retrIntern(softstring id);
507 public:
508 
509 
510  // don't reimplement this method; fix/enhance it in the module
511 
512 private:
513  final hash statIntern();
514 public:
515 
516 
517  // don't reimplement this method; fix/enhance it in the module
518 
519 private:
520  final *hash listIntern();
521 public:
522 
523 
524  // read a line from the socket (terminated with \n)
525 
526 private:
527  string readLine(timeout to);
528 public:
529 
530 
531  // gets a trimmed one-line response from the server, throws an exception if an error response is received
532  // don't reimplement this method; fix/enhance it in the module
533 
534 private:
535  final string getResponse();
536 public:
537 
538 
539  // gets a trimmed multi-line response from the server, throws an exception if an error response is received
540  // don't reimplement this method; fix/enhance it in the module
541 
542 private:
543  final list getResponseMulti();
544 public:
545 
546 
547  // gets a multi-line response from the server, throws an exception if an error response is received
548  // does not include the first line in the response
549  // don't reimplement this method; fix/enhance it in the module
550 
551 private:
552  final string getResponseMultiStr();
553 public:
554 
555 
556 
557 private:
558  log(string msg);
559 public:
560 
561 
562 
563 private:
564  logDbg(string msg);
565 public:
566 
567 
568  // don't reimplement this method; fix/enhance it in the module
569 
570 private:
571  final sendCommandIntern(string str, bool masked = False);
572 public:
573 
574 
575  // don't reimplement this method; fix/enhance it in the module
576 
577 private:
578  final list sendCommandMulti(string str);
579 public:
580 
581 
582  // don't reimplement this method; fix/enhance it in the module
583 
584 private:
585  final string sendCommandMultiStr(string str);
586 public:
587 
588 
589  // don't reimplement this method; fix/enhance it in the module
590 
591 private:
592  final string sendCommand(string str);
593 public:
594 
595 
596  // don't reimplement this method; fix/enhance it in the module
597 
598 private:
599  final string sendCommandMasked(string str);
600 public:
601 
602 
603 
604 private:
605  loginIntern(string r);
606 public:
607 
608 
609 
610 private:
611  doSSLIntern();
612 public:
613 
614 
615  // when this method returns without an exception, the object is in the TRANSACTION state
616 
617 private:
618  connectIntern();
619 public:
620 
621 
622 
623 private:
624  forceDisconnectIntern();
625 public:
626 
628  };
629 };