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 - 2014 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  * 2014-02-04 v1.3: David Nichols <david@qore.org>
34  + added socket instrumention support from Qore 0.8.9
35 
36  * 2013-05-22 v1.2: David Nichols <david@qore.org>
37  + uncommented the "connected" debug message
38 
39  * 2012-11-03 v1.1: David Nichols <david@qore.org>
40  + added the logPassword() methods and masked password by default in the debug log
41 
42  * 2012-09-04 v1.0: David Nichols <david@qore.org>
43  + doc updates only
44 
45  * 2012-06-12 v1.0: David Nichols <david@qore.org>
46  + initial release
47 
48  based on:
49  - http://tools.ietf.org/html/rfc1939 (POP3)
50 */
51 
85 
92 namespace Pop3Client {
94  const DefaultReadTimeout = 15s;
95 
97  const DefaultConnectTimeout = 30s;
98 
100 
113  class Pop3Client {
114 
115 public:
117  private :
118  Socket sock();
119 
120  // connect string
121  string connect;
122 
123  // ensures exclusive access to the object
124  Mutex mutex();
125 
126  // optional info log closure
127  *code log_info;
128 
129  // optional debug log closure
130  *code log_debug;
131 
132  // "tls" flag
133  bool tls = False;
134 
135  // "starttls" flag
136  bool starttls = False;
137 
138  // "noquit" flag
139  bool noquit = False;
140 
141  // authentication credentials
142  string user;
143  string pass;
144 
145  // logged in flag
146  bool logged_in = False;
147 
148  // read timeout in milliseconds
149  timeout readTimeout = DefaultReadTimeout;
150 
151  // connect timeout in milliseconds
152  timeout connectTimeout = DefaultConnectTimeout;
153 
154  // log password
155  bool log_pass = False;
156 
157  const MaxDebugLine = 2048;
158 
159 public:
161 
162  public :
164  const POP3Port = 110;
165 
167  const POP3SPort = 995;
168 
170  const Protocols = (
171  "pop3": ("tls": False, "port": POP3Port),
172  "pop3s": ("tls": True, "port": POP3SPort),
173  );
174 
175 public:
176 
178 
195  constructor(string url, *code log, *code dbglog);
196 
197 
199 
201  destructor();
202 
203 
205 
212  logPassword(bool pwd);
213 
214 
216 
222  bool logPassword();
223 
224 
226 
233  tls(bool tls);
234 
235 
237 
243  bool tls();
244 
245 
247 
254  starttls(bool starttls);
255 
256 
258 
264  bool starttls();
265 
266 
268 
275  noquit(bool noquit);
276 
277 
279 
288  bool noquit();
289 
290 
292 
304  connect();
305 
306 
308 
319  *hash getMail();
320 
321 
323 
338  hash stat();
339 
340 
342 
357  *hash list();
358 
359 
361 
372  del(softstring msg);
373 
374 
376 
385  del(list l);
386 
387 
389 
398  noop();
399 
400 
402 
411  reset();
412 
413 
415 
421  bool isConnected();
422 
423 
425 
430  disconnect();
431 
432 
434 
439  setReadTimeout(timeout to);
440 
441 
443 
448  int getReadTimeoutMs();
449 
450 
452 
458 
459 
461 
466  setConnectTimeout(timeout to);
467 
468 
470 
475  int getConnectTimeoutMs();
476 
477 
479 
485 
486 
488 
495  forceDisconnect();
496 
497 
499 
508  nothing clearWarningQueue();
509 
510 
512 
542  nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms = 1s);
543 
544 
546 
564  hash getUsageInfo();
565 
566 
568 
577  clearStats();
578 
579 
581  // don't reimplement this method; fix/enhance it in the module
582  final private disconnectIntern();
583 
584 
585  // don't reimplement this method; fix/enhance it in the module
586  final private MailMessage::Message retrIntern(softstring id);
587 
588 
589  // don't reimplement this method; fix/enhance it in the module
590  final private hash statIntern();
591 
592 
593  // don't reimplement this method; fix/enhance it in the module
594  final private *hash listIntern();
595 
596 
597  // read a line from the socket (terminated with \n)
598  private string readLine(timeout to);
599 
600 
601  // gets a trimmed one-line response from the server, throws an exception if an error response is received
602  // don't reimplement this method; fix/enhance it in the module
603  final private string getResponse();
604 
605 
606  // gets a trimmed multi-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 list getResponseMulti();
609 
610 
611  // gets a multi-line response from the server, throws an exception if an error response is received
612  // does not include the first line in the response
613  // don't reimplement this method; fix/enhance it in the module
614  final private string getResponseMultiStr();
615 
616 
617  private log(string msg);
618 
619 
620  private logDbg(string msg);
621 
622 
623  // don't reimplement this method; fix/enhance it in the module
624  final private sendCommandIntern(string str, bool masked = False);
625 
626 
627  // don't reimplement this method; fix/enhance it in the module
628  final private list sendCommandMulti(string str);
629 
630 
631  // don't reimplement this method; fix/enhance it in the module
632  final private string sendCommandMultiStr(string str);
633 
634 
635  // don't reimplement this method; fix/enhance it in the module
636  final private string sendCommand(string str);
637 
638 
639  // don't reimplement this method; fix/enhance it in the module
640  final private string sendCommandMasked(string str);
641 
642 
643  private loginIntern(string r);
644 
645 
646  private doSSLIntern();
647 
648 
649  // when this method returns without an exception, the object is in the TRANSACTION state
650  private connectIntern();
651 
652 
653  private forceDisconnectIntern();
654 
656  };
657 };
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:97
This class provides the interface to POP3 servers and supports optional TLS/SSL encryption.
Definition: Pop3Client.qm.dox.h:113
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:170
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:164
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:94
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:167