Qore MailMessage Module Reference  1.3
MailMessage.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file MailMessage.qm MailMessage module definition
3 
4 /* MailMessage.qm Copyright 2012 - 2017 Qore Technologies, s.r.o.
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 // require type declarations everywhere
33 // disallows access to backwards-compatible "noop" variants
34 // enables all warnings
35 
36 
96 
102 namespace MailMessage {
106 
111  const EncDefault = "default";
112 
114  const EncNone = "none";
115 
118 
121 
123  const Encodings = (
124  EncDefault,
125  EncNone,
126  EncBase64,
128  );
130 
132 
169  class Message {
170 
171 public:
173  private :
174  // the sender
175  string from;
176  // subject is a header field
177  string subject;
178 
179  // additional headers
180  hash headers; // hash of additional headers except the ones below
181  // message statuses
182  bool importance = False;
183  bool deliveryReceipt = False;
184  bool readReceipt = False;
185 
186  // names
187  list<string> to(); // list of names for to (header only) will be prefilled (and overwritten) with the recipients
188  list<string> cc(); // list of cc's
189  list<string> bcc(); // list of bcc's
190 
191  // message data itself
192  *data body;
193 
194  // message body content transfer encoding
195  string bodyEncoding = EncDefault;
196 
197  // message body content type
198  *string bodyContentType;
199 
200  // list of Attachments
201  list<Attachment> attachments();
202 
203  // list of Parts that are not Attachments (and not the main Message body - could be alternative representations of the body, for example)
204  list<Part> parts();
205 
206  string sender;
207 
208 public:
210 
211  public :
213  string mpboundary = replace(make_base64_string(string(now_us())), "=", "");
214 
215 public:
216 
218 
225  constructor(string n_sender, string n_subject);
226 
227 
229 
233  constructor(string msg);
234 
235 
237 
240  string serialize();
241 
242 
243 
244 private:
245  processPart(hash p);
246 public:
247 
248 
250  static *string getEmailAddress(string str);
251 
253  static bool checkEmailAddress(string str);
254 
256 
261  list<string> addTO(string recipient);
262 
263 
265 
270  list<string> addCC(string recipient);
271 
272 
274 
279  list<string> addBCC(string recipient);
280 
281 
283  *string getSender();
284 
285 
287  *string getFrom();
288 
289 
291  list<string> getTO();
292 
293 
295  list<string> getCC();
296 
297 
299  list<string> getBCC();
300 
301 
303  string getSubject();
304 
305 
307  list<string> getRecipients();
308 
309 
311 
318  bool sendPossible();
319 
320 
322 
330 
331 
333 
339  setBody(data n_body, string n_enc = EncDefault, *string n_content_type);
340 
341 
343 
347  addBody(string str);
348 
349 
351 
355  addBody(binary bin);
356 
357 
359  *data getBody();
360 
361 
363  string getBodyTransferEncoding();
364 
365 
367 
374  static hash parseHeader(string hdr, bool decode = True);
375 
377 
383  setHeader(string hdr);
384 
385 
387 
393  setHeader(list hdrs);
394 
395 
397 
401  setHeader(hash hdrs);
402 
403 
405 
409  addHeader(string hdr);
410 
411 
413 
417  addHeader(list hdrs);
418 
419 
421 
425  addHeader(hash hdrs);
426 
427 
429  softlist getHeader();
430 
431 
433  *hash getHeaders();
434 
435 
437 
442  bool important();
443 
444 
446 
451  important(softbool i);
452 
453 
455 
458  bool receiptRead();
459 
460 
462 
465  receiptRead(bool arg);
466 
467 
469 
472  bool receiptDelivery();
473 
474 
476 
479  receiptDelivery(bool arg);
480 
481 
483 
492  attach(string name, string mime, data att, string enc = EncDefault, *hash hdr);
493 
494 
496 
498  attach(Attachment att);
499 
500 
502  list<Attachment> getAttachments();
503 
504 
506 
508  list<Part> getParts();
509 
510 
512 
519  static string doHeaderValue(string hdr, string val, string eol = "\r\n", bool encode = True);
520 
522 
527  string getHeaderString(string eol = "\r\n", bool encode = True);
528 
529 
531 
533  string toString(bool include_body = False);
534 
535 
537 
539  string toLine();
540 
541 
543 
552  static string checkEncoding(data data, string enc, bool noneok = False);
553 
555 
561  static string encodeTransferData(data data, string enc, reference<hash> hdr);
562 
564  static string encodeData(data data, string mime, string disp, string enc);
565 
567 
573  static string getLine(reference<string> msg, reference<int> pos);
574 
576 
577 private:
578  list<string> getEnvelopeList();
579 public:
580 
582  };
583 
585 
591  class Part {
592 
593 public:
594  // no public members
595 private:
596 
597 public:
598 
600  private :
601  string name;
602  string mime;
603  data data;
605  string enc;
606  // any extra headers for the message
607  *hash headers;
608 
609 public:
610 
611  // will only be called internally when parsing a Message
612  constructor(string filename, string mimetype, data filedata, string encoding = EncDefault, *hash hdr);
613 
615 
617  string getName();
618 
619 
621  string getMime();
622 
623 
625  data getData();
626 
627 
629  string getTransferEncoding();
630 
631 
633  *hash getHeaders();
634 
635 
637  add(MultiPartMixedMessage mpm);
638 
639  };
640 
642 
657 class Attachment : public Part {
658 
659 public:
660  // no public members
661 private:
662 
663 public:
664 
666 
675  constructor(string name, string mime, data data, string enc = EncDefault, *hash hdr) ;
676 
677  };
678 };
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
string getHeaderString(string eol="\", bool encode=True)
returns a string of the message headers
list< Attachment > getAttachments()
returns a list of Attachment objects for the Message
addHeader(string hdr)
adds a header to the Message
class representing a MIME part of a Message
Definition: MailMessage.qm.dox.h:591
const Encodings
a list of all known content encoding schemes encodings
Definition: MailMessage.qm.dox.h:123
static string encodeTransferData(data data, string enc, reference< hash > hdr)
returns a string of message data according to the encoding passed
date now_us()
*string getSender()
returns the sender&#39;s address in display format
string toLine()
returns a single line string summarizing the Message
The Message class holds the information for a single email Message.
Definition: MailMessage.qm.dox.h:169
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
const True
string getSubject()
returns the subject of the Message
list< string > getTO()
returns the list of "To:" addresses
bool sendPossible()
returns True if the message can be sent, False if not
binary binary()
static string doHeaderValue(string hdr, string val, string eol="\", bool encode=True)
encodes a header value according to the parameters
list< string > getCC()
returns the list of "CC:" addresses
list< string > addBCC(string recipient)
add a recipient to the Message&#39;s bcc list
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:120
bool important()
returns the current importance setting
class representing a MIME Attachment for the Message
Definition: MailMessage.qm.dox.h:657
*data getBody()
returns the Message body
list< Part > getParts()
returns a list of non-attachment Part objects for the Message
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
string mpboundary
create a different multipart boundary string every time based on the current time ...
Definition: MailMessage.qm.dox.h:213
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 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:117
string getBodyTransferEncoding()
returns the transfer encoding for the mssage body (see Message Encodings for possible values) ...
list< string > getRecipients()
return all the email addresses the message will be sent to, a combination of the "To:", "CC:", and "BCC:" lists
const ContentTransEncQuotedPrintable
static string getLine(reference< string > msg, reference< int > pos)
returns the first "\r\n" terminated line from the argument, updates the byte position argument ...
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
const EncNone
no content transfer encoding (not recommended as SMTP servers break up long lines automatically) ...
Definition: MailMessage.qm.dox.h:114
static string encodeData(data data, string mime, string disp, string enc)
returns a string of message data according to the encoding passed
list< string > getBCC()
returns the list of "BCC:" addresses
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
bool receiptDelivery()
returns the delivery receipt setting
the MailMessage namespace holds all public definitions in the MailMessage module
Definition: MailMessage.qm.dox.h:102
hash hash(object obj)
checkSendPossible()
throws a MESSAGE-ERROR exception if the Message cannot be sent
list< string > addCC(string recipient)
add a recipient to the Message&#39;s cc list
list< string > addTO(string recipient)
add a recipient to the Message&#39;s recipient list
const EncDefault
default content transfer encoding depending on attachment type
Definition: MailMessage.qm.dox.h:111
string toString(bool include_body=False)
returns a multi-line string representing the Message