Qore Pop3Client Module Reference  1.1
 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 2012 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  * 2012-11-03 v1.1: David Nichols <david@qore.org>
34  + added the logPassword() methods and masked password by default in the debug log
35 
36  * 2012-09-04 v1.0: David Nichols <david@qore.org>
37  + doc updates only
38 
39  * 2012-06-12 v1.0: David Nichols <david@qore.org>
40  + initial release
41 
42  based on:
43  - http://tools.ietf.org/html/rfc1939 (POP3)
44 */
45 
79 
80 
86 namespace Pop3Client {
88  const DefaultReadTimeout = 15s;
89 
91  const DefaultConnectTimeout = 30s;
92 
94 
107  class Pop3Client {
108 
109 public:
111  private :
112  Socket sock();
113 
114  // connect string
115  string connect;
116 
117  // ensures exclusive access to the object
118  Mutex mutex();
119 
120  // optional info log closure
121  *code log_info;
122 
123  // optional debug log closure
124  *code log_debug;
125 
126  // "tls" flag
127  bool tls = False;
128 
129  // "starttls" flag
130  bool starttls = False;
131 
132  // "noquit" flag
133  bool noquit = False;
134 
135  // authentication credentials
136  string user;
137  string pass;
138 
139  // logged in flag
140  bool logged_in = False;
141 
142  // read timeout in milliseconds
143  timeout readTimeout = DefaultReadTimeout;
144 
145  // connect timeout in milliseconds
146  timeout connectTimeout = DefaultConnectTimeout;
147 
148  // log password
149  bool log_pass = False;
150 
151  const MaxDebugLine = 2048;
152 
153 public:
155 
156  public :
158  const POP3Port = 110;
159 
161  const POP3SPort = 995;
162 
164  const Protocols = (
165  "pop3": ("tls": False, "port": POP3Port),
166  "pop3s": ("tls": True, "port": POP3SPort),
167  );
168 
169 public:
170 
172 
189  constructor(string url, *code log, *code dbglog);
190 
191 
193 
195  destructor();
196 
197 
199 
206  logPassword(bool pwd);
207 
208 
210 
216  bool logPassword();
217 
218 
220 
227  tls(bool tls);
228 
229 
231 
237  bool tls();
238 
239 
241 
248  starttls(bool starttls);
249 
250 
252 
258  bool starttls();
259 
260 
262 
269  noquit(bool noquit);
270 
271 
273 
282  bool noquit();
283 
284 
286 
298  connect();
299 
300 
302 
313  *hash getMail();
314 
315 
317 
332  hash stat();
333 
334 
336 
351  *hash list();
352 
353 
355 
366  del(softstring msg);
367 
368 
370 
379  del(list l);
380 
381 
383 
392  noop();
393 
394 
396 
405  reset();
406 
407 
409 
415  bool isConnected();
416 
417 
419 
424  disconnect();
425 
426 
428 
433  setReadTimeout(timeout to);
434 
435 
437 
442  int getReadTimeoutMs();
443 
444 
446 
452 
453 
455 
460  setConnectTimeout(timeout to);
461 
462 
464 
469  int getConnectTimeoutMs();
470 
471 
473 
479 
480 
482 
489  forceDisconnect();
490 
491 
493  // don't reimplement this method; fix/enhance it in the module
494 
495 private:
496  final disconnectIntern();
497 public:
498 
499 
500  // don't reimplement this method; fix/enhance it in the module
501 
502 private:
503  final MailMessage::Message retrIntern(softstring id);
504 public:
505 
506 
507  // don't reimplement this method; fix/enhance it in the module
508 
509 private:
510  final hash statIntern();
511 public:
512 
513 
514  // don't reimplement this method; fix/enhance it in the module
515 
516 private:
517  final *hash listIntern();
518 public:
519 
520 
521  // read a line from the socket (terminated with \n)
522 
523 private:
524  string readLine(timeout to);
525 public:
526 
527 
528  // gets a trimmed one-line response from the server, throws an exception if an error response is received
529  // don't reimplement this method; fix/enhance it in the module
530 
531 private:
532  final string getResponse();
533 public:
534 
535 
536  // gets a trimmed multi-line response from the server, throws an exception if an error response is received
537  // don't reimplement this method; fix/enhance it in the module
538 
539 private:
540  final list getResponseMulti();
541 public:
542 
543 
544  // gets a multi-line response from the server, throws an exception if an error response is received
545  // does not include the first line in the response
546  // don't reimplement this method; fix/enhance it in the module
547 
548 private:
549  final string getResponseMultiStr();
550 public:
551 
552 
553 
554 private:
555  log(string msg);
556 public:
557 
558 
559 
560 private:
561  logDbg(string msg);
562 public:
563 
564 
565  // don't reimplement this method; fix/enhance it in the module
566 
567 private:
568  final sendCommandIntern(string str, bool masked = False);
569 public:
570 
571 
572  // don't reimplement this method; fix/enhance it in the module
573 
574 private:
575  final list sendCommandMulti(string str);
576 public:
577 
578 
579  // don't reimplement this method; fix/enhance it in the module
580 
581 private:
582  final string sendCommandMultiStr(string str);
583 public:
584 
585 
586  // don't reimplement this method; fix/enhance it in the module
587 
588 private:
589  final string sendCommand(string str);
590 public:
591 
592 
593  // don't reimplement this method; fix/enhance it in the module
594 
595 private:
596  final string sendCommandMasked(string str);
597 public:
598 
599 
600 
601 private:
602  loginIntern(string r);
603 public:
604 
605 
606 
607 private:
608  doSSLIntern();
609 public:
610 
611 
612  // when this method returns without an exception, the object is in the TRANSACTION state
613 
614 private:
615  connectIntern();
616 public:
617 
618 
619 
620 private:
621  forceDisconnectIntern();
622 public:
623 
625  };
626 };