Qore SmtpClient Module Reference 1.2

- Main Page
- Namespaces
- Classes

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
143 const DefaultConnectTimeout = 30s;
144
146 class Message : public MailMessage::Message {
147
148 public:
150
157 constructor(string sender, string subject);
158
159 };
160
162 class Attachment : public MailMessage::Attachment {
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
358 date getReadTimeoutDate();
359
360
362 setConnectTimeout(timeout to);
363
364
366 int getConnectTimeoutMs();
367
368
370 date getConnectTimeoutDate();
371
372
374
386 hash sendMessage(MailMessage::Message message);
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