Qore SmtpClient Module Reference  1.2
 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 - 2013 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  * 2012-11-24 v1.2: David Nichols <david@qore.org>:
36  + added support for parsing a full URL in the SmtpClient::constructor(); added protocol support and setting the username / password from the URL
37  + use Message::checkSendPossible() to throw a more descriptive exception if the message is incomplete and not ready to be sent
38  + 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
39 
40  * 2012-06-14 v1.1: David Nichols <david@qore.org>:
41  + removed the Message and Attachment classes to the MailMessage module to be reused in the Pop3Client module
42 
43  * 2012-05-21 v1.0: David Nichols <david@qore.org>:
44  + updated to a user module, added initial rudimentary ESMTP handling, STARTTLS and quoted-printable encoding support + the bane of all developers: documentation :)
45 
46  ritzinwo, 20090716
47 
48  based on:
49  - http://james.apache.org/server/rfclist/smtp/rfc0821.txt
50  - http://tools.ietf.org/html/rfc821: initial SMTP protocol spec
51  - http://tools.ietf.org/html/rfc1521: quoted printable & base 64 transfer encodings
52  - http://tools.ietf.org/html/rfc2045: mime headers, content types, etc
53  - http://tools.ietf.org/html/rfc2047: "Q" and "B" encoded words (implemented by the Mime module)
54  - http://tools.ietf.org/html/rfc2822: message structure, headers, body, etc
55 */
56 
130 
131 
138 namespace SmtpClient {
140  const DefaultReadTimeout = 15s;
141 
144 
147 
148 public:
150 
157  constructor(string sender, string subject);
158 
159  };
160 
163 
164 public:
165  };
166 
168 
171  class SmtpClient {
172 
173 public:
175  private :
176  Socket sock();
177 
178  // connect string
179  string connect;
180 
181  // ensures exclusive access to the object
182  Mutex mutex();
183 
184  bool nosend = False;
185 
186  // optional info log closure
187  *code log_info;
188 
189  // optional debug log closure
190  *code log_debug;
191 
192  // tls flag (ie \c "STARTTLS" flag; ie application layer security)
193  bool tls = False;
194 
195  // ssl flag (for TLS/SSL connections - ie transport layer instead of application layer security)
196  bool ssl = False;
197 
198  // esmtp flag
199  bool esmtp;
200 
201  // authentication credentials
202  *string user;
203  *string pass;
204 
205  // logged in flag
206  bool logged_in = False;
207 
208  // read timeout in milliseconds
209  timeout readTimeout = DefaultReadTimeout;
210 
211  // connect timeout in milliseconds
212  timeout connectTimeout = DefaultConnectTimeout;
213 
214  const MaxDebugLine = 2048;
215 
216 public:
218 
219  public :
221  const SmtpPort = 25;
222 
224  const SmtpsPort = 465;
225 
227  const EsmtpPort = 587;
228 
230  const Protocols = (
231  "smtp": (
232  "port": SmtpPort,
233  "ssl": False,
234  "tls": False,
235  ),
236  "smtps": (
237  "port": SmtpsPort,
238  "ssl": True,
239  "tls": False,
240  ),
241  "smtptls": (
242  "port": SmtpsPort,
243  "ssl": False,
244  "tls": True,
245  ),
246  "esmtp": (
247  "port": EsmtpPort,
248  "ssl": False,
249  "tls": False,
250  ),
251  "esmtptls": (
252  "port": EsmtpPort,
253  "ssl": False,
254  "tls": True,
255  ),
256  );
257 
258 public:
259 
261 
266  constructor(string host, softint port, *code log, *code dbglog);
267 
268 
270 
283  constructor(string url, *code log, *code dbglog);
284 
285 
287 
289  destructor();
290 
291 
293 
295  tls(bool tls);
296 
297 
299  bool tls();
300 
301 
303 
305  ssl(bool ssl);
306 
307 
309  bool ssl();
310 
311 
313 
320  setUserPass(string user, string pass);
321 
322 
324  test(bool ns);
325 
326 
328  bool test();
329 
330 
332 
336  connect();
337 
338 
340  bool isConnected();
341 
342 
344 
346  disconnect();
347 
348 
350  setReadTimeout(timeout to);
351 
352 
354  int getReadTimeoutMs();
355 
356 
359 
360 
362  setConnectTimeout(timeout to);
363 
364 
366  int getConnectTimeoutMs();
367 
368 
371 
372 
374 
387 
388 
390 
392  forceDisconnect();
393 
394 
396  // don't reimplement this method; fix/enhance it in the module
397 
398 private:
399  final disconnectIntern();
400 public:
401 
402 
403 
404 private:
405  log(string msg);
406 public:
407 
408 
409 
410 private:
411  logDbg(string msg);
412 public:
413 
414 
415 
416 private:
417  connectIntern();
418 public:
419 
420 
421  // send data over the socket
422 
423 private:
424  sendDataIntern(data str);
425 public:
426 
427 
428  // send data and log in the debug log if set
429 
430 private:
431  sendData(string str);
432 public:
433 
434 
435  // send data and log in the debug log if set
436 
437 private:
438  sendData(binary b);
439 public:
440 
441 
442  // send a command over the socket and return the response as a hash
443  // don't reimplement this method; fix/enhance it in the module
444 
445 private:
446  final hash sendCommand(string str);
447 public:
448 
449 
450  // read a line from the socket (terminated with \n)
451 
452 private:
453  string readLine(timeout to);
454 public:
455 
456 
457  // sends the message header (without body & attachments) to the SMTP server
458  // don't reimplement this method; fix/enhance it in the module
459 
460 private:
461  final hash sendMessageInfoIntern(MailMessage::Message message);
462 public:
463 
464 
465 
466 private:
467  forceDisconnectIntern();
468 public:
469 
471  };
472 };
473