Qore SmtpClient Module Reference  1.3
 All Classes Namespaces Functions Variables Groups Pages
SmtpClient.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file SmtpClient.qm SmtpClient module definition
3 
4 /* SmtpClient.qm Copyright 2012 - 2014 Qore Technologies, sro
5 
6  Original Authors: Wolfgang Ritzinger, Marian Bonda, Pavol Potoncok
7 
8  Permission is hereby granted, free of charge, to any person obtaining a
9  copy of this software and associated documentation files (the "Software"),
10  to deal in the Software without restriction, including without limitation
11  the rights to use, copy, modify, merge, publish, distribute, sublicense,
12  and/or sell copies of the Software, and to permit persons to whom the
13  Software is furnished to do so, subject to the following conditions:
14 
15  The above copyright notice and this permission notice shall be included in
16  all copies or substantial portions of the Software.
17 
18  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24  DEALINGS IN THE SOFTWARE.
25 */
26 
27 // minimum qore version
28 
29 // need mime definitions
30 
31 // need MailMessage classes
32 
33 
34 /* Version History
35  * 2014-02-04 v1.3: David Nichols <david@qore.org>:
36  + added socket instrumention support from Qore 0.8.9
37 
38  * 2013-11-25 v1.3: David Nichols <david@qore.org>:
39  + optimized connection and login code; HELO/EHLO and authorization are performed when connecting only; not before each email
40 
41  * 2012-11-24 v1.2: David Nichols <david@qore.org>:
42  + added support for parsing a full URL in the SmtpClient::constructor(); added protocol support and setting the username / password from the URL
43  + use Message::checkSendPossible() to throw a more descriptive exception if the message is incomplete and not ready to be sent
44  + implemented support for automatically detecting if the server accepts the STARTTLS command and, if so, automatically setting the STARTTLS flag if it's not already set
45 
46  * 2012-06-14 v1.1: David Nichols <david@qore.org>:
47  + removed the Message and Attachment classes to the MailMessage module to be reused in the Pop3Client module
48 
49  * 2012-05-21 v1.0: David Nichols <david@qore.org>:
50  + updated to a user module, added initial rudimentary ESMTP handling, STARTTLS and quoted-printable encoding support + the bane of all developers: documentation :)
51 
52  ritzinwo, 20090716
53 
54  based on:
55  - http://james.apache.org/server/rfclist/smtp/rfc0821.txt
56  - http://tools.ietf.org/html/rfc821: initial SMTP protocol spec
57  - http://tools.ietf.org/html/rfc1521: quoted printable & base 64 transfer encodings
58  - http://tools.ietf.org/html/rfc2045: mime headers, content types, etc
59  - http://tools.ietf.org/html/rfc2047: "Q" and "B" encoded words (implemented by the Mime module)
60  - http://tools.ietf.org/html/rfc2822: message structure, headers, body, etc
61 */
62 
136 
144 namespace SmtpClient {
146  const DefaultReadTimeout = 15s;
147 
150 
153 
154 public:
156 
163  constructor(string sender, string subject);
164 
165  };
166 
169 
170 public:
171  };
172 
174 
177  class SmtpClient {
178 
179 public:
181  private :
182  Socket sock();
183 
184  // connect string
185  string connect;
186 
187  // ensures exclusive access to the object
188  Mutex mutex();
189 
190  bool nosend = False;
191 
192  // optional info log closure
193  *code log_info;
194 
195  // optional debug log closure
196  *code log_debug;
197 
198  // tls flag (ie \c "STARTTLS" flag; ie application layer security)
199  bool tls = False;
200 
201  // ssl flag (for TLS/SSL connections - ie transport layer instead of application layer security)
202  bool ssl = False;
203 
204  // esmtp flag
205  bool esmtp;
206 
207  // authentication credentials
208  *string user;
209  *string pass;
210 
211  // logged in flag
212  bool logged_in = False;
213 
214  // read timeout in milliseconds
215  timeout readTimeout = DefaultReadTimeout;
216 
217  // connect timeout in milliseconds
218  timeout connectTimeout = DefaultConnectTimeout;
219 
220  // HELO/EHLO reply
221  hash hello_reply;
222 
223  const MaxDebugLine = 2048;
224 
225 public:
227 
228  public :
230  const SmtpPort = 25;
231 
233  const SmtpsPort = 465;
234 
236  const EsmtpPort = 587;
237 
239  const Protocols = (
240  "smtp": (
241  "port": SmtpPort,
242  "ssl": False,
243  "tls": False,
244  ),
245  "smtps": (
246  "port": SmtpsPort,
247  "ssl": True,
248  "tls": False,
249  ),
250  "smtptls": (
251  "port": SmtpsPort,
252  "ssl": False,
253  "tls": True,
254  ),
255  "esmtp": (
256  "port": EsmtpPort,
257  "ssl": False,
258  "tls": False,
259  ),
260  "esmtptls": (
261  "port": EsmtpPort,
262  "ssl": False,
263  "tls": True,
264  ),
265  );
266 
267 public:
268 
270 
275  constructor(string host, softint port, *code log, *code dbglog);
276 
277 
279 
292  constructor(string url, *code log, *code dbglog);
293 
294 
296 
298  destructor();
299 
300 
302 
304  tls(bool tls);
305 
306 
308  bool tls();
309 
310 
312 
314  ssl(bool ssl);
315 
316 
318  bool ssl();
319 
320 
322 
329  setUserPass(string user, string pass);
330 
331 
333  test(bool ns);
334 
335 
337  bool test();
338 
339 
341 
345  connect();
346 
347 
349  bool isConnected();
350 
351 
353 
355  disconnect();
356 
357 
359  setReadTimeout(timeout to);
360 
361 
363  int getReadTimeoutMs();
364 
365 
368 
369 
371  setConnectTimeout(timeout to);
372 
373 
375  int getConnectTimeoutMs();
376 
377 
380 
381 
383 
396 
397 
399 
401  forceDisconnect();
402 
403 
405 
414  nothing clearWarningQueue();
415 
416 
418 
448  nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms = 1s);
449 
450 
452 
470  hash getUsageInfo();
471 
472 
474 
483  clearStats();
484 
485 
487  // don't reimplement this method; fix/enhance it in the module
488  final private disconnectIntern();
489 
490 
491  private log(string msg);
492 
493 
494  private logDbg(string msg);
495 
496 
497  private connectIntern();
498 
499 
500  private loginIntern();
501 
502 
503  // send data over the socket
504  private sendDataIntern(data str);
505 
506 
507  // send data and log in the debug log if set
508  private sendData(string str);
509 
510 
511  // send data and log in the debug log if set
512  private sendData(binary b);
513 
514 
515  // send a command over the socket and return the response as a hash
516  // don't reimplement this method; fix/enhance it in the module
517  final private hash sendCommand(string str);
518 
519 
520  // read a line from the socket (terminated with \n)
521  private string readLine(timeout to);
522 
523 
524  // sends the message header (without body & attachments) to the SMTP server
525  // don't reimplement this method; fix/enhance it in the module
526  final private hash sendMessageInfoIntern(MailMessage::Message message);
527 
528 
529  private forceDisconnectIntern();
530 
532  };
533 };
534 
date date(date dt)
date getConnectTimeoutDate()
returns the connect timeout as a relative time value
const SmtpPort
default SMTP port
Definition: SmtpClient.qm.dox.h:230
the class that&#39;s used to communicate with an SMTP server and supports optional TLS/SSL encryption ...
Definition: SmtpClient.qm.dox.h:177
int getReadTimeoutMs()
returns the read timeout as an integer giving milliseconds
setUserPass(string user, string pass)
sets the username and password for authenticated connections
const True
setConnectTimeout(timeout to)
sets the connect timeout
nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms=1s)
Sets a Queue object to receive socket warnings.
bool tls()
returns the TLS/SSL flag
binary binary()
const DefaultReadTimeout
15 second read timeout
Definition: SmtpClient.qm.dox.h:146
const DefaultConnectTimeout
30 second connect timeout
Definition: SmtpClient.qm.dox.h:149
destructor()
disconnects if connected and destroys the object
const False
for backwards-compatibility only
Definition: SmtpClient.qm.dox.h:168
constructor(string host, softint port, *code log, *code dbglog)
creates the SmtpClient object
forceDisconnect()
force disconnect of socket without error
nothing clearWarningQueue()
Removes any warning Queue object from the Socket.
bool ssl()
returns the SSL connection flag
const EsmtpPort
default ESMTP port
Definition: SmtpClient.qm.dox.h:236
date getReadTimeoutDate()
returns the read timeout as a relative time value
for backwards-compatibility and convenience
Definition: SmtpClient.qm.dox.h:152
disconnect()
disconnect from the server
bool isConnected()
return connection status
bool test()
returns the test mode flag
constructor(string sender, string subject)
creates a Message object from the arguments given; this variant of the constructor is designed to be ...
hash sendMessage(MailMessage::Message message)
send a Message to the server
connect()
Connect to the server with the connection parameters set in the constructor()
const SmtpsPort
default SMTPS port; note that this port is currently assigned to source-specific multicast audio/vide...
Definition: SmtpClient.qm.dox.h:233
const Protocols
procotol config
Definition: SmtpClient.qm.dox.h:239
hash hash(object obj)
int getConnectTimeoutMs()
returns the connect timeout as an integer giving milliseconds
setReadTimeout(timeout to)
sets the read timeout
clearStats()
Clears performance statistics.
hash getUsageInfo()
Returns performance statistics for the socket.