Qore SmtpClient Module Reference 1.4

- Main Page
- Related Pages
- 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 - 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
152 const DefaultConnectTimeout = 30s;
153
155 class Message : public MailMessage::Message {
156
157 public:
159
166 constructor(string sender, string subject);
167
168 };
169
171 class Attachment : public MailMessage::Attachment {
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(date dt)
SmtpClient::SmtpClient::getConnectTimeoutDate
date getConnectTimeoutDate()
returns the connect timeout as a relative time value
SmtpClient::SmtpClient::SmtpPort
const SmtpPort
default SMTP port
Definition: SmtpClient.qm.dox.h:233
SmtpClient::SmtpClient
the class that&#39;s used to communicate with an SMTP server and supports optional TLS/SSL encryption ...
Definition: SmtpClient.qm.dox.h:180
SmtpClient::SmtpClient::getReadTimeoutMs
int getReadTimeoutMs()
returns the read timeout as an integer giving milliseconds
SmtpClient::SmtpClient::setUserPass
setUserPass(string user, string pass)
sets the username and password for authenticated connections
MailMessage::Message
True
const True
SmtpClient::SmtpClient::setConnectTimeout
setConnectTimeout(timeout to)
sets the connect timeout
SmtpClient::SmtpClient::setWarningQueue
nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms=1s)
Sets a Queue object to receive socket warnings.
SmtpClient::SmtpClient::tls
bool tls()
returns the TLS/SSL flag
binary
binary binary()
SmtpClient::DefaultReadTimeout
const DefaultReadTimeout
15 second read timeout
Definition: SmtpClient.qm.dox.h:149
SmtpClient::DefaultConnectTimeout
const DefaultConnectTimeout
30 second connect timeout
Definition: SmtpClient.qm.dox.h:152
SmtpClient::SmtpClient::destructor
destructor()
disconnects if connected and destroys the object
False
const False
SmtpClient::Attachment
for backwards-compatibility only
Definition: SmtpClient.qm.dox.h:171
SmtpClient::SmtpClient::constructor
constructor(string host, softint port, *code log, *code dbglog)
creates the SmtpClient object
SmtpClient::SmtpClient::forceDisconnect
forceDisconnect()
force disconnect of socket without error
MailMessage::Attachment
SmtpClient::SmtpClient::clearWarningQueue
nothing clearWarningQueue()
Removes any warning Queue object from the Socket.
SmtpClient::SmtpClient::ssl
bool ssl()
returns the SSL connection flag
SmtpClient::SmtpClient::EsmtpPort
const EsmtpPort
default ESMTP port
Definition: SmtpClient.qm.dox.h:239
SmtpClient::SmtpClient::getReadTimeoutDate
date getReadTimeoutDate()
returns the read timeout as a relative time value
SmtpClient::Message
for backwards-compatibility and convenience
Definition: SmtpClient.qm.dox.h:155
SmtpClient::SmtpClient::disconnect
disconnect()
disconnect from the server
SmtpClient::SmtpClient::isConnected
bool isConnected()
return connection status
SmtpClient::SmtpClient::test
bool test()
returns the test mode flag
SmtpClient::Message::constructor
constructor(string sender, string subject)
creates a Message object from the arguments given; this variant of the constructor is designed to be ...
SmtpClient::SmtpClient::sendMessage
hash sendMessage(MailMessage::Message message)
send a Message to the server
SmtpClient::SmtpClient::connect
connect()
Connect to the server with the connection parameters set in the constructor()
SmtpClient::SmtpClient::SmtpsPort
const SmtpsPort
default SMTPS port; note that this port is currently assigned to source-specific multicast audio/vide...
Definition: SmtpClient.qm.dox.h:236
SmtpClient::SmtpClient::Protocols
const Protocols
procotol config
Definition: SmtpClient.qm.dox.h:242
hash
hash hash(object obj)
SmtpClient::SmtpClient::getConnectTimeoutMs
int getConnectTimeoutMs()
returns the connect timeout as an integer giving milliseconds
SmtpClient::SmtpClient::setReadTimeout
setReadTimeout(timeout to)
sets the read timeout
SmtpClient::SmtpClient::clearStats
clearStats()
Clears performance statistics.
SmtpClient::SmtpClient::getUsageInfo
hash getUsageInfo()
Returns performance statistics for the socket.