Qore Pop3Client Module Reference  1.5
 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 - 2017 Qore Technologies, s.r.o.
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 // requires the ConnectionProvider module
32 
33 // assume local var scope, do not use "$" for vars, members, and method calls
34 
35 
102 
109 namespace Pop3Client {
111  const DefaultReadTimeout = 15s;
112 
115 
117 
130  class Pop3Client {
131 
132 public:
134  private :
135  Socket sock();
136 
137  // connect string
138  string connect;
139 
140  // ensures exclusive access to the object
141  Mutex mutex();
142 
143  // optional info log closure
144  *code log_info;
145 
146  // optional debug log closure
147  *code log_debug;
148 
149  // "tls" flag
150  bool tls = False;
151 
152  // "starttls" flag
153  bool starttls = False;
154 
155  // "noquit" flag
156  bool noquit = False;
157 
158  // authentication credentials
159  string user;
160  string pass;
161 
162  // logged in flag
163  bool logged_in = False;
164 
165  // read timeout in milliseconds
166  timeout readTimeout = DefaultReadTimeout;
167 
168  // connect timeout in milliseconds
169  timeout connectTimeout = DefaultConnectTimeout;
170 
171  // log password
172  bool log_pass = False;
173 
174  const MaxDebugLine = 2048;
175 
176 public:
178 
179  public :
181  const POP3Port = 110;
182 
184  const POP3SPort = 995;
185 
187  const Protocols = (
188  "pop3": ("tls": False, "port": POP3Port),
189  "pop3s": ("tls": True, "port": POP3SPort),
190  );
191 
192 public:
193 
195 
212  constructor(string url, *code log, *code dbglog);
213 
214 
216 
218  destructor();
219 
220 
222 
229  logPassword(bool pwd);
230 
231 
233 
239  bool logPassword();
240 
241 
243 
250  tls(bool n_tls);
251 
252 
254 
260  bool tls();
261 
262 
264 
271  starttls(bool n_starttls);
272 
273 
275 
281  bool starttls();
282 
283 
285 
292  noquit(bool n_noquit);
293 
294 
296 
305  bool noquit();
306 
307 
309 
321  connect();
322 
323 
325 
336  *hash getMail();
337 
338 
340 
355  hash stat();
356 
357 
359 
374  *hash list();
375 
376 
378 
389  del(softstring msg);
390 
391 
393 
402  del(list l);
403 
404 
406 
415  noop();
416 
417 
419 
428  reset();
429 
430 
432 
438  bool isConnected();
439 
440 
442 
447  disconnect();
448 
449 
451 
456  setReadTimeout(timeout to);
457 
458 
460 
465  int getReadTimeoutMs();
466 
467 
469 
475 
476 
478 
483  setConnectTimeout(timeout to);
484 
485 
487 
492  int getConnectTimeoutMs();
493 
494 
496 
502 
503 
505 
512  forceDisconnect();
513 
514 
516 
525  nothing clearWarningQueue();
526 
527 
529 
559  nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms = 1s);
560 
561 
563 
581  hash getUsageInfo();
582 
583 
585 
594  clearStats();
595 
596 
598  // don't reimplement this method; fix/enhance it in the module
599 
600 private:
601  final disconnectIntern();
602 public:
603 
604 
605  // don't reimplement this method; fix/enhance it in the module
606 
607 private:
608  final MailMessage::Message retrIntern(softstring id);
609 public:
610 
611 
612  // don't reimplement this method; fix/enhance it in the module
613 
614 private:
615  final hash statIntern();
616 public:
617 
618 
619  // don't reimplement this method; fix/enhance it in the module
620 
621 private:
622  final *hash listIntern();
623 public:
624 
625 
626  // read a line from the socket (terminated with \n)
627 
628 private:
629  string readLine(timeout to);
630 public:
631 
632 
633  // gets a trimmed one-line response from the server, throws an exception if an error response is received
634  // don't reimplement this method; fix/enhance it in the module
635 
636 private:
637  final string getResponse();
638 public:
639 
640 
641  // gets a trimmed multi-line response from the server, throws an exception if an error response is received
642  // don't reimplement this method; fix/enhance it in the module
643 
644 private:
645  final list getResponseMulti();
646 public:
647 
648 
649  // gets a multi-line response from the server, throws an exception if an error response is received
650  // does not include the first line in the response
651  // don't reimplement this method; fix/enhance it in the module
652 
653 private:
654  final string getResponseMultiStr();
655 public:
656 
657 
658 
659 private:
660  log(string msg);
661 public:
662 
663 
664 
665 private:
666  logDbg(string msg);
667 public:
668 
669 
670  // don't reimplement this method; fix/enhance it in the module
671 
672 private:
673  final sendCommandIntern(string str, bool masked = False);
674 public:
675 
676 
677  // don't reimplement this method; fix/enhance it in the module
678 
679 private:
680  final list sendCommandMulti(string str);
681 public:
682 
683 
684  // don't reimplement this method; fix/enhance it in the module
685 
686 private:
687  final string sendCommandMultiStr(string str);
688 public:
689 
690 
691  // don't reimplement this method; fix/enhance it in the module
692 
693 private:
694  final string sendCommand(string str);
695 public:
696 
697 
698  // don't reimplement this method; fix/enhance it in the module
699 
700 private:
701  final string sendCommandMasked(string str);
702 public:
703 
704 
705 
706 private:
707  loginIntern(string r);
708 public:
709 
710 
711 
712 private:
713  doSSLIntern();
714 public:
715 
716 
717  // when this method returns without an exception, the object is in the TRANSACTION state
718 
719 private:
720  connectIntern();
721 public:
722 
723 
724 
725 private:
726  forceDisconnectIntern();
727 public:
728 
730  };
731 
733 
740 
741 public:
743 
750  constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh) ;
751 
752 
754  string getType();
755 
756 
758 
763 
764 
766 
774 private:
775  Pop3Client getImpl(bool connect = True, *hash rtopts);
776 public:
777 
778 
780  static Pop3Connection make(string name, string desc, string url, bool monitor, *hash opts, hash urlh);
781  };
782 };
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 "starttls" flag (RFC 2595)
int getConnectTimeoutMs()
returns the connect timeout as an integer giving milliseconds
class for POP3 connections; returns an object of class Pop3Client for receiving or polling for emails...
Definition: Pop3Client.qm.dox.h:739
const DefaultConnectTimeout
30 second connect timeout
Definition: Pop3Client.qm.dox.h:114
constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh)
creates the Pop3Connection object
This class provides the interface to POP3 servers and supports optional TLS/SSL encryption.
Definition: Pop3Client.qm.dox.h:130
nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
Sets a Queue object to receive socket warnings.
const True
const False
*hash list()
returns a hash with message information from the "LIST" command (http://tools.ietf.org/html/rfc1939#page-6)
Pop3Client getImpl(bool connect=True, *hash rtopts)
returns a Pop3Client object
forceDisconnect()
force disconnect of socket without error
del(softstring msg)
sends a "DELE" 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()
static Pop3Connection make(string name, string desc, string url, bool monitor, *hash opts, hash urlh)
static 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 "noquit" flag; if this flag is True, then no "QUIT" command is sent to the POP3 server whe...
setConnectTimeout(timeout to)
sets the connect timeout
*hash getRuntimeOptions()
returns runtime options
string getType()
returns "pop3"
noop()
send a "NOOP" command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server ...
const Protocols
accepted protocols
Definition: Pop3Client.qm.dox.h:187
hash stat()
returns a hash with status information from the "STAT" command (http://tools.ietf.org/html/rfc1939#page-6)
const POP3Port
default POP3 port
Definition: Pop3Client.qm.dox.h:181
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:111
reset()
send a "RSET" 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:184