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 Wolfgang Ritzinger, Marian Bonda, Pavol Potoncok
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  * 2012-11-24 v1.2: David Nichols <david@qore.org>:
34  + added support for parsing a full URL in the SmtpClient::constructor(); added protocol support and setting the username / password from the URL
35  + use Message::checkSendPossible() to throw a more descriptive exception if the message is incomplete and not ready to be sent
36  + 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
37 
38  * 2012-06-14 v1.1: David Nichols <david@qore.org>:
39  + removed the Message and Attachment classes to the MailMessage module to be reused in the Pop3Client module
40 
41  * 2012-05-21 v1.0: David Nichols <david@qore.org>:
42  + updated to a user module, added initial rudimentary ESMTP handling, STARTTLS and quoted-printable encoding support + the bane of all developers: documentation :)
43 
44  ritzinwo, 20090716
45 
46  based on:
47  - http://james.apache.org/server/rfclist/smtp/rfc0821.txt
48  - http://tools.ietf.org/html/rfc821: initial SMTP protocol spec
49  - http://tools.ietf.org/html/rfc1521: quoted printable & base 64 transfer encodings
50  - http://tools.ietf.org/html/rfc2045: mime headers, content types, etc
51  - http://tools.ietf.org/html/rfc2047: "Q" and "B" encoded words (implemented by the Mime module)
52  - http://tools.ietf.org/html/rfc2822: message structure, headers, body, etc
53 */
54 
128 
129 
136 namespace SmtpClient {
138  const DefaultReadTimeout = 15s;
139 
142 
145 
146 public:
148 
155  constructor(string sender, string subject);
156 
157  };
158 
161 
162 public:
163  };
164 
166 
169  class SmtpClient {
170 
171 public:
173  private :
174  Socket sock();
175 
176  // connect string
177  string connect;
178 
179  // ensures exclusive access to the object
180  Mutex mutex();
181 
182  bool nosend = False;
183 
184  // optional info log closure
185  *code log_info;
186 
187  // optional debug log closure
188  *code log_debug;
189 
190  // tls flag (ie \c "STARTTLS" flag; ie application layer security)
191  bool tls = False;
192 
193  // ssl flag (for TLS/SSL connections - ie transport layer instead of application layer security)
194  bool ssl = False;
195 
196  // esmtp flag
197  bool esmtp;
198 
199  // authentication credentials
200  *string user;
201  *string pass;
202 
203  // logged in flag
204  bool logged_in = False;
205 
206  // read timeout in milliseconds
207  timeout readTimeout = DefaultReadTimeout;
208 
209  // connect timeout in milliseconds
210  timeout connectTimeout = DefaultConnectTimeout;
211 
212  const MaxDebugLine = 2048;
213 
214 public:
216 
217  public :
219  string mpboundary = replace(makeBase64String(string(now_us())), "=", "");
220 
222  const SmtpPort = 25;
223 
225  const SmtpsPort = 465;
226 
228  const EsmtpPort = 587;
229 
231  const Protocols = (
232  "smtp": (
233  "port": SmtpPort,
234  "ssl": False,
235  "tls": False,
236  ),
237  "smtps": (
238  "port": SmtpsPort,
239  "ssl": True,
240  "tls": False,
241  ),
242  "smtptls": (
243  "port": SmtpsPort,
244  "ssl": False,
245  "tls": True,
246  ),
247  "esmtp": (
248  "port": EsmtpPort,
249  "ssl": False,
250  "tls": False,
251  ),
252  "esmtptls": (
253  "port": EsmtpPort,
254  "ssl": False,
255  "tls": True,
256  ),
257  );
258 
259 public:
260 
262 
267  constructor(string host, softint port, *code log, *code dbglog);
268 
269 
271 
284  constructor(string url, *code log, *code dbglog);
285 
286 
288 
290  destructor();
291 
292 
294 
296  tls(bool tls);
297 
298 
300  bool tls();
301 
302 
304 
306  ssl(bool ssl);
307 
308 
310  bool ssl();
311 
312 
314 
321  setUserPass(string user, string pass);
322 
323 
325  test(bool ns);
326 
327 
329  bool test();
330 
331 
333 
337  connect();
338 
339 
341  bool isConnected();
342 
343 
345 
347  disconnect();
348 
349 
351  setReadTimeout(timeout to);
352 
353 
355  int getReadTimeoutMs();
356 
357 
360 
361 
363  setConnectTimeout(timeout to);
364 
365 
367  int getConnectTimeoutMs();
368 
369 
372 
373 
375 
388 
389 
391 
393  forceDisconnect();
394 
395 
397  // don't reimplement this method; fix/enhance it in the module
398 
399 private:
400  final disconnectIntern();
401 public:
402 
403 
404 
405 private:
406  log(string msg);
407 public:
408 
409 
410 
411 private:
412  logDbg(string msg);
413 public:
414 
415 
416 
417 private:
418  connectIntern();
419 public:
420 
421 
422  // send data over the socket
423 
424 private:
425  sendDataIntern(data str);
426 public:
427 
428 
429  // send data and log in the debug log if set
430 
431 private:
432  sendData(string str);
433 public:
434 
435 
436  // send data and log in the debug log if set
437 
438 private:
439  sendData(binary b);
440 public:
441 
442 
443  // send a command over the socket and return the response as a hash
444  // don't reimplement this method; fix/enhance it in the module
445 
446 private:
447  final hash sendCommand(string str);
448 public:
449 
450 
451  // read a line from the socket (terminated with \n)
452 
453 private:
454  string readLine(timeout to);
455 public:
456 
457 
458  // sends the message header (without body & attachments) to the SMTP server
459  // don't reimplement this method; fix/enhance it in the module
460 
461 private:
462  final hash sendMessageHeaderIntern(MailMessage::Message message);
463 public:
464 
465 
466 
467 private:
468  forceDisconnectIntern();
469 public:
470 
472  };
473 };
474