Qore MailMessage Module Reference  1.2
MailMessage.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file MailMessage.qm MailMessage module definition
3 
4 /* MailMessage.qm Copyright 2012 - 2015 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 // assume local var scope, do not use "$" for vars, members, and method calls
32 
33 
34 /* Version History
35  * 2015-11-11 v1.2: David Nichols <david@qore.org>
36  + converted to new-style
37 
38  * 2013-06-05 v1.1: David Nichols <david@qore.org>
39  + added the Message::serialize() method
40 
41  * 2012-11-02 v1.0.4: David Nichols <david@qore.org>
42  + minor doc corrections and non-functional code changes
43 
44  * 2012-11-02 v1.0.3: David Nichols <david@qore.org>
45  + requires Mime module 1.3 for the MultiPartMessage::parseBody() method
46  + fixed a bug where the part/attachment content-type was set to the content-type of the message
47  + try to get the filename of attachments from the content-type header if not set in the content-disposition header
48  + message parts that themselves have parts are now supported
49  + fixed recognizing mime messages with additional text after the version number (ex: "Mime-Version: 1.0 (Mac OS X Mail 6.2 \(1499\))")
50 
51  * 2012-09-17 v1.0.2: David Nichols <david@qore.org>
52  + use <string>::isPrintableAscii() to determine which mail headers need encoding
53 
54  * 2012-09-17 v1.0.1: David Nichols <david@qore.org>
55  + fixed a bug encoding mail headers where mail headers requiring encoding were not encoded and those not requiring encoding were encoded with Q encoding
56 
57  * 2012-06-14 v1.0: David Nichols <david@qore.org>
58  + moved from the SmtpClient module to an independent module to also support the Pop3Client class
59 */
60 
85 
91 namespace MailMessage {
95 
100  const EncDefault = "default";
101 
103  const EncNone = "none";
104 
107 
110 
112  const Encodings = (
113  EncDefault,
114  EncNone,
115  EncBase64,
117  );
119 
121 
158  class Message {
159 
160 public:
162  private :
163  // the sender
164  string from;
165  // subject is a header field
166  string subject;
167 
168  // additional headers
169  hash headers; // hash of additional headers except the ones below
170  // message statuses
171  bool importance = False;
172  bool deliveryReceipt = False;
173  bool readReceipt = False;
174 
175  // names
176  list to = (); // list of names for to (header only) will be prefilled (and overwritten) with the recipients
177  list cc = (); // list of cc's
178  list bcc = (); // list of bcc's
179 
180  // message data itself
181  *data body;
182 
183  // message body content transfer encoding
184  string bodyEncoding = EncDefault;
185 
186  // message body content type
187  *string bodyContentType;
188 
189  // list of Attachments
190  list attachments = ();
191 
192  // list of Parts that are not Attachments (and not the main Message body - could be alternative representations of the body, for example)
193  list parts = ();
194 
195  string sender;
196 
197 public:
199 
200  public :
202  string mpboundary = replace(make_base64_string(string(now_us())), "=", "");
203 
204 public:
205 
207 
214  constructor(string n_sender, string n_subject);
215 
216 
218 
222  constructor(string msg);
223 
224 
226 
229  string serialize();
230 
231 
232  private processPart(hash p);
233 
234 
236  static *string getEmailAddress(string str);
237 
239  static bool checkEmailAddress(string str);
240 
242 
247  list addTO(string recipient);
248 
249 
251 
256  list addCC(string recipient);
257 
258 
260 
265  list addBCC(string recipient);
266 
267 
269  *string getSender();
270 
271 
273  *string getFrom();
274 
275 
277  list getTO();
278 
279 
281  list getCC();
282 
283 
285  list getBCC();
286 
287 
289  string getSubject();
290 
291 
294 
295 
297 
304  bool sendPossible();
305 
306 
308 
316 
317 
319 
325  setBody(data n_body, string n_enc = EncDefault, *string n_content_type);
326 
327 
329 
333  addBody(string str);
334 
335 
337 
341  addBody(binary bin);
342 
343 
345  *data getBody();
346 
347 
349  string getBodyTransferEncoding();
350 
351 
353 
360  static hash parseHeader(string hdr, bool decode = True);
361 
363 
369  setHeader(string hdr);
370 
371 
373 
379  setHeader(list hdrs);
380 
381 
383 
387  setHeader(hash hdrs);
388 
389 
391 
395  addHeader(string hdr);
396 
397 
399 
403  addHeader(list hdrs);
404 
405 
407 
411  addHeader(hash hdrs);
412 
413 
415  softlist getHeader();
416 
417 
419  *hash getHeaders();
420 
421 
423 
428  bool important();
429 
430 
432 
437  important(softbool i);
438 
439 
441 
444  bool receiptRead();
445 
446 
448 
451  receiptRead(bool arg);
452 
453 
455 
458  bool receiptDelivery();
459 
460 
462 
465  receiptDelivery(bool arg);
466 
467 
469 
478  attach(string name, string mime, data att, string enc = EncDefault, *hash hdr);
479 
480 
482 
484  attach(Attachment att);
485 
486 
489 
490 
492 
494  list getParts();
495 
496 
498 
505  static string doHeaderValue(string hdr, string val, string eol = "\r\n", bool encode = True);
506 
507 
509 
514  string getHeaderString(string eol = "\r\n", bool encode = True);
515 
516 
518 
520  string toString(bool include_body = False);
521 
522 
524 
526  string toLine();
527 
528 
530 
539  static string checkEncoding(data data, string enc, bool noneok = False);
540 
542 
548  static string encodeTransferData(data data, string enc, reference hdr);
549 
551  static string encodeData(data data, string mime, string disp, string enc);
552 
554 
560  static string getLine(reference msg, reference pos);
561 
563  private list getEnvelopeList();
564 
566  };
567 
569 
575  class Part {
576 
577 public:
578  // no public members
579 private:
580 
581 public:
582 
584  private :
585  string name;
586  string mime;
587  data data;
589  string enc;
590  // any extra headers for the message
591  *hash headers;
592 
593 public:
594 
595  // will only be called internally when parsing a Message
596  constructor(string filename, string mimetype, data filedata, string encoding = EncDefault, *hash hdr);
597 
599 
601  string getName();
602 
603 
605  string getMime();
606 
607 
609  data getData();
610 
611 
613  string getTransferEncoding();
614 
615 
617  *hash getHeaders();
618 
619 
621  add(MultiPartMixedMessage mpm);
622 
623  };
624 
626 
641 class Attachment : public Part {
642 
643 public:
644  // no public members
645 private:
646 
647 public:
648 
650 
659  constructor(string name, string mime, data data, string enc = EncDefault, *hash hdr) ;
660 
661  };
662 };
string getHeaderString(string eol="\r\n", bool encode=True)
returns a string of the message headers
data getData()
returns the data of the Part
static hash parseHeader(string hdr, bool decode=True)
parses the given string representing a header line and returns a single key - value hash for the head...
addBody(string str)
concatenates a string to the message body
addHeader(string hdr)
adds a header to the Message
class representing a MIME part of a Message
Definition: MailMessage.qm.dox.h:575
const Encodings
a list of all known content encoding schemes encodings
Definition: MailMessage.qm.dox.h:112
date now_us()
*string getSender()
returns the sender's address in display format
string toLine()
returns a single line string summarizing the Message
list getParts()
returns a list of non-attachment Part objects for the Message
list getBCC()
returns the list of "BCC:" addresses
list getTO()
returns the list of "To:" addresses
The Message class holds the information for a single email Message.
Definition: MailMessage.qm.dox.h:158
string make_base64_string(string str, softint maxlinelen=-1)
static *string getEmailAddress(string str)
fetch the email address out of a sender/rcpt string
softlist getHeader()
returns the current Message headers as a list of strings
*hash getHeaders()
returns any headers for the Part
static string encodeTransferData(data data, string enc, reference hdr)
returns a string of message data according to the encoding passed
list getCC()
returns the list of "CC:" addresses
const True
string getMime()
returns the mime type of the Part
string getSubject()
returns the subject of the Message
list addCC(string recipient)
add a recipient to the Message's cc list
bool sendPossible()
returns True if the message can be sent, False if not
binary binary()
const ContentTransEncBase64
attach(string name, string mime, data att, string enc=EncDefault, *hash hdr)
creates an attachment for the Message
const False
string replace(string str, string source, string target, int start=0, int end=-1)
list list(...)
*hash getHeaders()
returns the current Message headers as a hash
const EncQuotedPrintable
"quoted-printable" content transfer encoding
Definition: MailMessage.qm.dox.h:109
bool important()
returns the current importance setting
class representing a MIME Attachment for the Message
Definition: MailMessage.qm.dox.h:641
*data getBody()
returns the Message body
list getAttachments()
returns a list of Attachment objects for the Message
constructor(string name, string mime, data data, string enc=EncDefault, *hash hdr)
creates an Attachment object for a Message object
list addTO(string recipient)
add a recipient to the Message's recipient list
constructor(string n_sender, string n_subject)
creates a Message object from the arguments given; this variant of the constructor is designed to be ...
bool receiptRead()
returns the current read delivery receipt setting
list getRecipients()
return all the email addresses the message will be sent to, a combination of the "To:", "CC:", and "BCC:" lists
string mpboundary
create a different multipart boundary string every time based on the current time ...
Definition: MailMessage.qm.dox.h:202
static string checkEncoding(data data, string enc, bool noneok=False)
checks the data against the encoding and returns the new encoding (if the encoding is EncDefault for ...
string getTransferEncoding()
returns the transfer encoding of the Part
string serialize()
serializes the message to a string that can be sent to an SMTP server, for example ...
const EncBase64
base-64 content transfer encoding
Definition: MailMessage.qm.dox.h:106
static string doHeaderValue(string hdr, string val, string eol="\r\n", bool encode=True)
encodes a header value according to the parameters
string getBodyTransferEncoding()
returns the transfer encoding for the mssage body (see Message Encodings for possible values) ...
const ContentTransEncQuotedPrintable
setHeader(string hdr)
sets/replaces the Message headers
setBody(data n_body, string n_enc=EncDefault, *string n_content_type)
sets or replaces the Message body
static string getLine(reference msg, reference pos)
returns the first "\r\n" terminated line from the argument, updates the byte position argument ...
const EncNone
no content transfer encoding (not recommended as SMTP servers break up long lines automatically) ...
Definition: MailMessage.qm.dox.h:103
add(MultiPartMixedMessage mpm)
adds itself to a multipart/mixed message
static string encodeData(data data, string mime, string disp, string enc)
returns a string of message data according to the encoding passed
string getName()
returns the name of the Part
static bool checkEmailAddress(string str)
returns True if the string contains an email address, False if not
*string getFrom()
returns the sender's email address
list addBCC(string recipient)
add a recipient to the Message's bcc list
bool receiptDelivery()
returns the delivery receipt setting
the MailMessage namespace holds all public definitions in the MailMessage module
Definition: MailMessage.qm.dox.h:91
hash hash(object obj)
checkSendPossible()
throws a MESSAGE-ERROR exception if the Message cannot be sent
const EncDefault
default content transfer encoding depending on attachment type
Definition: MailMessage.qm.dox.h:100
string toString(bool include_body=False)
returns a multi-line string representing the Message