Qore Pop3Client Module Reference  1.4
 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 - 2015 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 // assume local var scope, do not use "$" for vars, members, and method calls
32 
33 
34 /* Version History
35  * 2015-11-11 v1.4: David Nichols <david@qore.org>
36  + converted to new-style
37 
38  * 2014-02-04 v1.3: David Nichols <david@qore.org>
39  + added socket instrumention support from Qore 0.8.9
40 
41  * 2013-05-22 v1.2: David Nichols <david@qore.org>
42  + uncommented the "connected" debug message
43 
44  * 2012-11-03 v1.1: David Nichols <david@qore.org>
45  + added the logPassword() methods and masked password by default in the debug log
46 
47  * 2012-09-04 v1.0: David Nichols <david@qore.org>
48  + doc updates only
49 
50  * 2012-06-12 v1.0: David Nichols <david@qore.org>
51  + initial release
52 
53  based on:
54  - http://tools.ietf.org/html/rfc1939 (POP3)
55 */
56 
90 
97 namespace Pop3Client {
99  const DefaultReadTimeout = 15s;
100 
103 
105 
118  class Pop3Client {
119 
120 public:
122  private :
123  Socket sock();
124 
125  // connect string
126  string connect;
127 
128  // ensures exclusive access to the object
129  Mutex mutex();
130 
131  // optional info log closure
132  *code log_info;
133 
134  // optional debug log closure
135  *code log_debug;
136 
137  // "tls" flag
138  bool tls = False;
139 
140  // "starttls" flag
141  bool starttls = False;
142 
143  // "noquit" flag
144  bool noquit = False;
145 
146  // authentication credentials
147  string user;
148  string pass;
149 
150  // logged in flag
151  bool logged_in = False;
152 
153  // read timeout in milliseconds
154  timeout readTimeout = DefaultReadTimeout;
155 
156  // connect timeout in milliseconds
157  timeout connectTimeout = DefaultConnectTimeout;
158 
159  // log password
160  bool log_pass = False;
161 
162  const MaxDebugLine = 2048;
163 
164 public:
166 
167  public :
169  const POP3Port = 110;
170 
172  const POP3SPort = 995;
173 
175  const Protocols = (
176  "pop3": ("tls": False, "port": POP3Port),
177  "pop3s": ("tls": True, "port": POP3SPort),
178  );
179 
180 public:
181 
183 
200  constructor(string url, *code log, *code dbglog);
201 
202 
204 
206  destructor();
207 
208 
210 
217  logPassword(bool pwd);
218 
219 
221 
227  bool logPassword();
228 
229 
231 
238  tls(bool n_tls);
239 
240 
242 
248  bool tls();
249 
250 
252 
259  starttls(bool n_starttls);
260 
261 
263 
269  bool starttls();
270 
271 
273 
280  noquit(bool n_noquit);
281 
282 
284 
293  bool noquit();
294 
295 
297 
309  connect();
310 
311 
313 
324  *hash getMail();
325 
326 
328 
343  hash stat();
344 
345 
347 
362  *hash list();
363 
364 
366 
377  del(softstring msg);
378 
379 
381 
390  del(list l);
391 
392 
394 
403  noop();
404 
405 
407 
416  reset();
417 
418 
420 
426  bool isConnected();
427 
428 
430 
435  disconnect();
436 
437 
439 
444  setReadTimeout(timeout to);
445 
446 
448 
453  int getReadTimeoutMs();
454 
455 
457 
463 
464 
466 
471  setConnectTimeout(timeout to);
472 
473 
475 
480  int getConnectTimeoutMs();
481 
482 
484 
490 
491 
493 
500  forceDisconnect();
501 
502 
504 
513  nothing clearWarningQueue();
514 
515 
517 
547  nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms = 1s);
548 
549 
551 
569  hash getUsageInfo();
570 
571 
573 
582  clearStats();
583 
584 
586  // don't reimplement this method; fix/enhance it in the module
587  final private disconnectIntern();
588 
589 
590  // don't reimplement this method; fix/enhance it in the module
591  final private MailMessage::Message retrIntern(softstring id);
592 
593 
594  // don't reimplement this method; fix/enhance it in the module
595  final private hash statIntern();
596 
597 
598  // don't reimplement this method; fix/enhance it in the module
599  final private *hash listIntern();
600 
601 
602  // read a line from the socket (terminated with \n)
603  private string readLine(timeout to);
604 
605 
606  // gets a trimmed one-line response from the server, throws an exception if an error response is received
607  // don't reimplement this method; fix/enhance it in the module
608  final private string getResponse();
609 
610 
611  // gets a trimmed multi-line response from the server, throws an exception if an error response is received
612  // don't reimplement this method; fix/enhance it in the module
613  final private list getResponseMulti();
614 
615 
616  // gets a multi-line response from the server, throws an exception if an error response is received
617  // does not include the first line in the response
618  // don't reimplement this method; fix/enhance it in the module
619  final private string getResponseMultiStr();
620 
621 
622  private log(string msg);
623 
624 
625  private logDbg(string msg);
626 
627 
628  // don't reimplement this method; fix/enhance it in the module
629  final private sendCommandIntern(string str, bool masked = False);
630 
631 
632  // don't reimplement this method; fix/enhance it in the module
633  final private list sendCommandMulti(string str);
634 
635 
636  // don't reimplement this method; fix/enhance it in the module
637  final private string sendCommandMultiStr(string str);
638 
639 
640  // don't reimplement this method; fix/enhance it in the module
641  final private string sendCommand(string str);
642 
643 
644  // don't reimplement this method; fix/enhance it in the module
645  final private string sendCommandMasked(string str);
646 
647 
648  private loginIntern(string r);
649 
650 
651  private doSSLIntern();
652 
653 
654  // when this method returns without an exception, the object is in the TRANSACTION state
655  private connectIntern();
656 
657 
658  private forceDisconnectIntern();
659 
661  };
662 };
date date(date dt)
disconnect()
disconnect from the server
bool isConnected()
return connection status
setReadTimeout(timeout to)
sets the read timeout
bool starttls()
returns the &quot;starttls&quot; flag (RFC 2595)
int getConnectTimeoutMs()
returns the connect timeout as an integer giving milliseconds
nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms=1s)
Sets a Queue object to receive socket warnings.
const DefaultConnectTimeout
30 second connect timeout
Definition: Pop3Client.qm.dox.h:102
This class provides the interface to POP3 servers and supports optional TLS/SSL encryption.
Definition: Pop3Client.qm.dox.h:118
const True
const False
*hash list()
returns a hash with message information from the &quot;LIST&quot; command (http://tools.ietf.org/html/rfc1939#page-6)
forceDisconnect()
force disconnect of socket without error
del(softstring msg)
sends a &quot;DELE&quot; command (http://tools.ietf.org/html/rfc1939#page-8) to the POP3 server to mark the giv...
bool logPassword()
returns the log password flag
nothing clearWarningQueue()
Removes any warning Queue object from the Socket.
hash getUsageInfo()
Returns performance statistics for the socket.
connect()
Connect to the server with the connection parameters set in the constructor()
int getReadTimeoutMs()
returns the read timeout as an integer giving milliseconds
*hash getMail()
returns a hash of mail messages keyed by message ID or NOTHING if no messages are available on the se...
bool noquit()
return the &quot;noquit&quot; flag; if this flag is True, then no &quot;QUIT&quot; command is sent to the POP3 server whe...
setConnectTimeout(timeout to)
sets the connect timeout
noop()
send a &quot;NOOP&quot; command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server ...
const Protocols
accepted protocols
Definition: Pop3Client.qm.dox.h:175
hash stat()
returns a hash with status information from the &quot;STAT&quot; command (http://tools.ietf.org/html/rfc1939#page-6)
const POP3Port
default POP3 port
Definition: Pop3Client.qm.dox.h:169
clearStats()
Clears performance statistics.
date getReadTimeoutDate()
returns the read timeout as a relative time value
date getConnectTimeoutDate()
returns the connect timeout as a relative time value
constructor(string url, *code log, *code dbglog)
creates the Pop3Client object
hash hash(object obj)
const DefaultReadTimeout
15 second read timeout
Definition: Pop3Client.qm.dox.h:99
reset()
send a &quot;RSET&quot; command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server which will unmar...
bool tls()
returns the TLS/SSL flag
destructor()
disconnects if connected and destroys the object
const POP3SPort
default POP3S port
Definition: Pop3Client.qm.dox.h:172