Qore MailMessage Module Reference  1.1
 All Classes Namespaces Functions Variables Groups Pages
MailMessage.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file MailMessage.qm MailMessage module definition
3 
4 /* MailMessage.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 
32 /* Version History
33  * 2013-06-05 v1.1: David Nichols <david@qore.org>
34  + added the Message::serialize() method
35 
36  * 2012-11-02 v1.0.4: David Nichols <david@qore.org>
37  + minor doc corrections and non-functional code changes
38 
39  * 2012-11-02 v1.0.3: David Nichols <david@qore.org>
40  + requires Mime module 1.3 for the MultiPartMessage::parseBody() method
41  + fixed a bug where the part/attachment content-type was set to the content-type of the message
42  + try to get the filename of attachments from the content-type header if not set in the content-disposition header
43  + message parts that themselves have parts are now supported
44  + fixed recognizing mime messages with additional text after the version number (ex: "Mime-Version: 1.0 (Mac OS X Mail 6.2 \(1499\))")
45 
46  * 2012-09-17 v1.0.2: David Nichols <david@qore.org>
47  + use <string>::isPrintableAscii() to determine which mail headers need encoding
48 
49  * 2012-09-17 v1.0.1: David Nichols <david@qore.org>
50  + fixed a bug encoding mail headers where mail headers requiring encoding were not encoded and those not requiring encoding were encoded with Q encoding
51 
52  * 2012-06-14 v1.0: David Nichols <david@qore.org>
53  + moved from the SmtpClient module to an independent module to also support the Pop3Client class
54 */
55 
80 
86 namespace MailMessage {
90 
95  const EncDefault = "default";
96 
98  const EncNone = "none";
99 
102 
105 
107  const Encodings = (
108  EncDefault,
109  EncNone,
110  EncBase64,
112  );
114 
116 
153  class Message {
154 
155 public:
157  private :
158  // the sender
159  string from;
160  // subject is a header field
161  string subject;
162 
163  // additional headers
164  hash headers; // hash of additional headers except the ones below
165  // message statuses
166  bool importance = False;
167  bool deliveryReceipt = False;
168  bool readReceipt = False;
169 
170  // names
171  list to = (); // list of names for to (header only) will be prefilled (and overwritten) with the recipients
172  list cc = (); // list of cc's
173  list bcc = (); // list of bcc's
174 
175  // message data itself
176  *data body;
177 
178  // message body content transfer encoding
179  string bodyEncoding = EncDefault;
180 
181  // message body content type
182  *string bodyContentType;
183 
184  // list of Attachments
185  list attachments = ();
186 
187  // list of Parts that are not Attachments (and not the main Message body - could be alternative representations of the body, for example)
188  list parts = ();
189 
190  string sender;
191 
192 public:
194 
195  public :
197  string mpboundary = replace(makeBase64String(string(now_us())), "=", "");
198 
199 public:
200 
202 
209  constructor(string sender, string subject);
210 
211 
213 
217  constructor(string msg);
218 
219 
221 
224  string serialize();
225 
226 
227  private processPart(hash p);
228 
229 
231  static *string getEmailAddress(string str);
232 
234  static bool checkEmailAddress(string str);
235 
237 
242  list addTO(string recipient);
243 
244 
246 
251  list addCC(string recipient);
252 
253 
255 
260  list addBCC(string recipient);
261 
262 
264  *string getSender();
265 
266 
268  *string getFrom();
269 
270 
272  list getTO();
273 
274 
276  list getCC();
277 
278 
280  list getBCC();
281 
282 
284  string getSubject();
285 
286 
289 
290 
292 
299  bool sendPossible();
300 
301 
303 
311 
312 
314 
320  setBody(data body, string enc = EncDefault, *string content_type);
321 
322 
324 
328  addBody(string str);
329 
330 
332 
336  addBody(binary bin);
337 
338 
340  *data getBody();
341 
342 
344  string getBodyTransferEncoding();
345 
346 
348 
355  static hash parseHeader(string hdr, bool decode = True);
356 
358 
364  setHeader(string hdr);
365 
366 
368 
374  setHeader(list hdrs);
375 
376 
378 
382  setHeader(hash hdrs);
383 
384 
386 
390  addHeader(string hdr);
391 
392 
394 
398  addHeader(list hdrs);
399 
400 
402 
406  addHeader(hash hdrs);
407 
408 
410  softlist getHeader();
411 
412 
414  *hash getHeaders();
415 
416 
418 
423  bool important();
424 
425 
427 
432  important(softbool i);
433 
434 
436 
439  bool receiptRead();
440 
441 
443 
446  receiptRead(bool arg);
447 
448 
450 
453  bool receiptDelivery();
454 
455 
457 
460  receiptDelivery(bool arg);
461 
462 
464 
473  attach(string name, string mime, data att, string enc = EncDefault, *hash hdr);
474 
475 
477 
479  attach(Attachment att);
480 
481 
484 
485 
487 
489  list getParts();
490 
491 
493 
500  static string doHeaderValue(string hdr, string val, string eol = "\r\n", bool encode = True);
501 
502 
504 
509  string getHeaderString(string eol = "\r\n", bool encode = True);
510 
511 
513 
515  string toString(bool body = False);
516 
517 
519 
521  string toLine();
522 
523 
525 
534  static string checkEncoding(data data, string enc, bool noneok = False);
535 
537 
543  static string encodeTransferData(data data, string enc, reference hdr);
544 
546  static string encodeData(data data, string mime, string disp, string enc);
547 
549 
555  static string getLine(reference msg, reference pos);
556 
558  private list getEnvelopeList();
559 
561  };
562 
564 
570  class Part {
571 
572 public:
573  // no public members
574 private:
575 
576 public:
577 
579  private :
580  string name;
581  string mime;
582  data data;
584  string enc;
585  // any extra headers for the message
586  *hash headers;
587 
588 public:
589 
590  // will only be called internally when parsing a Message
591  constructor(string name, string mime, data data, string enc = EncDefault, *hash hdr);
592 
594 
596  string getName();
597 
598 
600  string getMime();
601 
602 
604  data getData();
605 
606 
608  string getTransferEncoding();
609 
610 
612  *hash getHeaders();
613 
614 
616  add(MultiPartMixedMessage mpm);
617 
618  };
619 
621 
636 class Attachment : public Part {
637 
638 public:
639  // no public members
640 private:
641 
642 public:
643 
645 
654  constructor(string name, string mime, data data, string enc = EncDefault, *hash hdr);
655 
656  };
657 };
constructor(string sender, string subject)
creates a Message object from the arguments given; this variant of the constructor is designed to be ...
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:570
const Encodings
a list of all known content encoding schemes encodings
Definition: MailMessage.qm.dox.h:107
date now_us()
*string getSender()
returns the sender&#39;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 &quot;BCC:&quot; addresses
list getTO()
returns the list of &quot;To:&quot; addresses
The Message class holds the information for a single email Message.
Definition: MailMessage.qm.dox.h:153
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 &quot;CC:&quot; 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&#39;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
&quot;quoted-printable&quot; content transfer encoding
Definition: MailMessage.qm.dox.h:104
bool important()
returns the current importance setting
class representing a MIME Attachment for the Message
Definition: MailMessage.qm.dox.h:636
*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&#39;s recipient list
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 &quot;To:&quot;, &quot;CC:&quot;, and &quot;BCC:&quot; lists
string mpboundary
create a different multipart boundary string every time based on the current time ...
Definition: MailMessage.qm.dox.h:197
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 toString(bool body=False)
returns a multi-line string representing the Message
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:101
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
static string getLine(reference msg, reference pos)
returns the first &quot;\r\n&quot; 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:98
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&#39;s email address
list addBCC(string recipient)
add a recipient to the Message&#39;s bcc list
bool receiptDelivery()
returns the delivery receipt setting
setBody(data body, string enc=EncDefault, *string content_type)
sets or replaces the Message body
hash hash(object obj)
string makeBase64String(string str, softint maxlinelen=-1)
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:95