Qore SmtpClient Module Reference  1.4
 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-03-17 v1.4: David Nichols <david@qore.org>:
36  + fixed missing username and missing password errors
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-11-25 v1.3: David Nichols <david@qore.org>:
42  + optimized connection and login code; HELO/EHLO and authorization are performed when connecting only; not before each email
43 
44  * 2012-11-24 v1.2: David Nichols <david@qore.org>:
45  + added support for parsing a full URL in the SmtpClient::constructor(); added protocol support and setting the username / password from the URL
46  + use Message::checkSendPossible() to throw a more descriptive exception if the message is incomplete and not ready to be sent
47  + 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
48 
49  * 2012-06-14 v1.1: David Nichols <david@qore.org>:
50  + removed the Message and Attachment classes to the MailMessage module to be reused in the Pop3Client module
51 
52  * 2012-05-21 v1.0: David Nichols <david@qore.org>:
53  + updated to a user module, added initial rudimentary ESMTP handling, STARTTLS and quoted-printable encoding support + the bane of all developers: documentation :)
54 
55  ritzinwo, 20090716
56 
57  based on:
58  - http://james.apache.org/server/rfclist/smtp/rfc0821.txt
59  - http://tools.ietf.org/html/rfc821: initial SMTP protocol spec
60  - http://tools.ietf.org/html/rfc1521: quoted printable & base 64 transfer encodings
61  - http://tools.ietf.org/html/rfc2045: mime headers, content types, etc
62  - http://tools.ietf.org/html/rfc2047: "Q" and "B" encoded words (implemented by the Mime module)
63  - http://tools.ietf.org/html/rfc2822: message structure, headers, body, etc
64 */
65 
139 
147 namespace SmtpClient {
149  const DefaultReadTimeout = 15s;
150 
153 
156 
157 public:
159 
166  constructor(string sender, string subject);
167 
168  };
169 
172 
173 public:
174  };
175 
177 
180  class SmtpClient {
181 
182 public:
184  private :
185  Socket sock();
186 
187  // connect string
188  string connect;
189 
190  // ensures exclusive access to the object
191  Mutex mutex();
192 
193  bool nosend = False;
194 
195  // optional info log closure
196  *code log_info;
197 
198  // optional debug log closure
199  *code log_debug;
200 
201  // tls flag (ie \c "STARTTLS" flag; ie application layer security)
202  bool tls = False;
203 
204  // ssl flag (for TLS/SSL connections - ie transport layer instead of application layer security)
205  bool ssl = False;
206 
207  // esmtp flag
208  bool esmtp;
209 
210  // authentication credentials
211  *string user;
212  *string pass;
213 
214  // logged in flag
215  bool logged_in = False;
216 
217  // read timeout in milliseconds
218  timeout readTimeout = DefaultReadTimeout;
219 
220  // connect timeout in milliseconds
221  timeout connectTimeout = DefaultConnectTimeout;
222 
223  // HELO/EHLO reply
224  hash hello_reply;
225 
226  const MaxDebugLine = 2048;
227 
228 public:
230 
231  public :
233  const SmtpPort = 25;
234 
236  const SmtpsPort = 465;
237 
239  const EsmtpPort = 587;
240 
242  const Protocols = (
243  "smtp": (
244  "port": SmtpPort,
245  "ssl": False,
246  "tls": False,
247  ),
248  "smtps": (
249  "port": SmtpsPort,
250  "ssl": True,
251  "tls": False,
252  ),
253  "smtptls": (
254  "port": SmtpsPort,
255  "ssl": False,
256  "tls": True,
257  ),
258  "esmtp": (
259  "port": EsmtpPort,
260  "ssl": False,
261  "tls": False,
262  ),
263  "esmtptls": (
264  "port": EsmtpPort,
265  "ssl": False,
266  "tls": True,
267  ),
268  );
269 
270 public:
271 
273 
278  constructor(string host, softint port, *code log, *code dbglog);
279 
280 
282 
295  constructor(string url, *code log, *code dbglog);
296 
297 
299 
301  destructor();
302 
303 
305 
307  tls(bool tls);
308 
309 
311  bool tls();
312 
313 
315 
317  ssl(bool ssl);
318 
319 
321  bool ssl();
322 
323 
325 
332  setUserPass(string user, string pass);
333 
334 
336  test(bool ns);
337 
338 
340  bool test();
341 
342 
344 
348  connect();
349 
350 
352  bool isConnected();
353 
354 
356 
358  disconnect();
359 
360 
362  setReadTimeout(timeout to);
363 
364 
366  int getReadTimeoutMs();
367 
368 
370  date getReadTimeoutDate();
371 
372 
374  setConnectTimeout(timeout to);
375 
376 
378  int getConnectTimeoutMs();
379 
380 
382  date getConnectTimeoutDate();
383 
384 
386 
398  hash sendMessage(MailMessage::Message message);
399 
400 
402 
404  forceDisconnect();
405 
406 
408 
417  nothing clearWarningQueue();
418 
419 
421 
451  nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms = 1s);
452 
453 
455 
473  hash getUsageInfo();
474 
475 
477 
486  clearStats();
487 
488 
490  // don't reimplement this method; fix/enhance it in the module
491  final private disconnectIntern();
492 
493 
494  private log(string msg);
495 
496 
497  private logDbg(string msg);
498 
499 
500  private connectIntern();
501 
502 
503  private loginIntern();
504 
505 
506  // send data over the socket
507  private sendDataIntern(data str);
508 
509 
510  // send data and log in the debug log if set
511  private sendData(string str);
512 
513 
514  // send data and log in the debug log if set
515  private sendData(binary b);
516 
517 
518  // send a command over the socket and return the response as a hash
519  // don't reimplement this method; fix/enhance it in the module
520  final private hash sendCommand(string str);
521 
522 
523  // read a line from the socket (terminated with \n)
524  private string readLine(timeout to);
525 
526 
527  // sends the message header (without body & attachments) to the SMTP server
528  // don't reimplement this method; fix/enhance it in the module
529  final private hash sendMessageInfoIntern(MailMessage::Message message);
530 
531 
532  private forceDisconnectIntern();
533 
535  };
536 };
537 
date date(date dt)
the class that's used to communicate with an SMTP server and supports optional TLS/SSL encryption ...
Definition: SmtpClient.qm.dox.h:180
const True
binary binary()
const DefaultReadTimeout
15 second read timeout
Definition: SmtpClient.qm.dox.h:149
const DefaultConnectTimeout
30 second connect timeout
Definition: SmtpClient.qm.dox.h:152
const False
for backwards-compatibility only
Definition: SmtpClient.qm.dox.h:171
for backwards-compatibility and convenience
Definition: SmtpClient.qm.dox.h:155
constructor(string sender, string subject)
creates a Message object from the arguments given; this variant of the constructor is designed to be ...
hash hash(object obj)