Poco::Net

class MailMessage

Library: Net
Package: Mail
Header: Poco/Net/MailMessage.h

Description

This class represents an e-mail message for use with the SMTPClientSession and POPClientSession classes.

MailMessage supports both old-style plain text messages, as well as MIME multipart mail messages with attachments.

For multi-part messages, the following content transfer encodings are supported: 7bit, 8bit, quoted-printable and base64.

Inheritance

Direct Base Classes: MessageHeader

All Base Classes: MessageHeader, NameValueCollection

Member Summary

Member Functions: addAttachment, addContent, addPart, addRecipient, appendRecipient, contentTransferEncodingToString, createPartStore, encodeWord, getContent, getContentType, getDate, getSender, getSubject, handlePart, isMultipart, lineLength, makeMultipart, parts, read, readHeader, readMultipart, readPart, recipients, setContent, setContentType, setDate, setRecipientHeaders, setRecipients, setSender, setSubject, write, writeEncoded, writeHeader, writeMultipart, writePart

Inherited Functions: add, begin, clear, empty, end, erase, find, get, getFieldLimit, has, hasToken, operator =, operator [], quote, read, set, setFieldLimit, size, splitElements, splitParameters, swap, write

Nested Classes

struct Part

 more...

Types

PartVec

typedef std::vector < Part > PartVec;

Recipients

typedef std::vector < MailRecipient > Recipients;

Enumerations

ContentDisposition

CONTENT_INLINE

CONTENT_ATTACHMENT

ContentTransferEncoding

ENCODING_7BIT

ENCODING_8BIT

ENCODING_QUOTED_PRINTABLE

ENCODING_BASE64

Constructors

MailMessage

MailMessage(
    PartStoreFactory * pStoreFactory = 0
);

Creates an empty MailMessage.

If pStoreFactory is not null, message attachments will be handled by the object created by the factory. Most common reason is to temporarily save attachments to the file system in order to avoid potential memory exhaustion when attachment files are very large.

Destructor

~MailMessage virtual

virtual ~MailMessage();

Destroys the MailMessage.

Member Functions

addAttachment

void addAttachment(
    const std::string & name,
    PartSource * pSource,
    ContentTransferEncoding encoding = ENCODING_BASE64
);

Adds an attachment to the mail message by calling addPart(name, pSource, CONTENT_ATTACHMENT, encoding);

The part name, and the filename specified in the part source must not contain any non-ASCII characters. To include non-ASCII characters in the part name or filename, use RFC 2047 word encoding (see encodeWord()).

addContent

void addContent(
    PartSource * pSource,
    ContentTransferEncoding encoding = ENCODING_QUOTED_PRINTABLE
);

Adds a part to the mail message by calling addPart("", pSource, CONTENT_INLINE, encoding);

The part name, and the filename specified in the part source must not contain any non-ASCII characters. To include non-ASCII characters in the part name or filename, use RFC 2047 word encoding (see encodeWord()).

addPart

void addPart(
    const std::string & name,
    PartSource * pSource,
    ContentDisposition disposition,
    ContentTransferEncoding encoding
);

Adds a part/attachment to the mail message.

The MailMessage takes ownership of the PartSource and deletes it when it is no longer needed.

The MailMessage will be converted to a multipart message if it is not already one.

The part name, and the filename specified in the part source must not contain any non-ASCII characters. To include non-ASCII characters in the part name or filename, use RFC 2047 word encoding (see encodeWord()).

addRecipient

void addRecipient(
    const MailRecipient & recipient
);

Adds a recipient for the message.

createPartStore

PartSource * createPartStore(
    const std::string & content,
    const std::string & mediaType,
    const std::string & filename = ""
);

Returns either default StringPartSource part store or, if the part store factory was provided during contruction, the one created by PartStoreFactory. Returned part store is allocated on the heap; it is caller's responsibility to delete it after use. Typical use is handler passing it back to MailMessage, which takes care of the cleanup.

encodeWord static

static std::string encodeWord(
    const std::string & text,
    const std::string & charset = "UTF-8"
);

If the given string contains non-ASCII characters, encodes the given string using RFC 2047 "Q" word encoding.

The given text must already be encoded in the character set given in charset (default is UTF-8).

Returns the encoded string, or the original string if it consists only of ASCII characters.

getContent inline

const std::string & getContent() const;

Returns the content of the mail message.

A content will only be returned for single-part messages. The content of multi-part mail messages will be reported through the registered PartHandler.

getContentType

const std::string & getContentType() const;

Returns the content type for the message.

getDate

Poco::Timestamp getDate() const;

Returns the value of the Date header.

getSender

const std::string & getSender() const;

Returns the sender of the message (taken from the From header field).

getSubject

const std::string & getSubject() const;

Returns the subject of the message.

isMultipart

bool isMultipart() const;

Returns true if and only if the message is a multipart message.

parts inline

const PartVec & parts() const;

Returns const reference to the vector containing part stores.

read

void read(
    std::istream & istr,
    PartHandler & handler
);

Reads the MailMessage from the given input stream.

If the message has multiple parts, the parts are reported to the PartHandler. If the message is not a multi-part message, the content is stored in a string available by calling getContent().

read virtual

void read(
    std::istream & istr
);

Reads the MailMessage from the given input stream.

The raw message (including all MIME parts) is stored in a string and available by calling getContent().

recipients inline

const Recipients & recipients() const;

Returns the recipients of the message.

setContent

void setContent(
    const std::string & content,
    ContentTransferEncoding encoding = ENCODING_QUOTED_PRINTABLE
);

Sets the content of the mail message.

If the content transfer encoding is ENCODING_7BIT or ENCODING_8BIT, the content string must be formatted according to the rules of an internet email message.

The message will be sent as a single-part message.

Note that single CR or LF characters as line delimiters must not be used. Content lines always should be terminated with a proper CRLF sequence.

setContentType

void setContentType(
    const std::string & mediaType
);

Sets the content type for the message.

setContentType

void setContentType(
    const MediaType & mediaType
);

Sets the content type for the message.

setDate

void setDate(
    const Poco::Timestamp & dateTime
);

Sets the Date header to the given date/time value.

setRecipients

void setRecipients(
    const Recipients & recipient
);

Clears existing and sets new recipient list for the message.

setSender

void setSender(
    const std::string & sender
);

Sets the sender of the message (which ends up in the From header field).

The sender must either be a valid email address, or a real name followed by an email address enclosed in < and >.

The sender must not contain any non-ASCII characters. To include non-ASCII characters in the sender, use RFC 2047 word encoding (see encodeWord()).

setSubject

void setSubject(
    const std::string & subject
);

Sets the subject of the message.

The subject must not contain any non-ASCII characters. To include non-ASCII characters in the subject, use RFC 2047 word encoding (see encodeWord()).

write virtual

void write(
    std::ostream & ostr
) const;

Writes the mail message to the given output stream.

appendRecipient protected static

static void appendRecipient(
    const MailRecipient & recipient,
    std::string & str
);

contentTransferEncodingToString protected static

static const std::string & contentTransferEncodingToString(
    ContentTransferEncoding encoding
);

handlePart protected

void handlePart(
    std::istream & istr,
    const MessageHeader & header,
    PartHandler & handler
);

lineLength protected static

static int lineLength(
    const std::string & str
);

makeMultipart protected

void makeMultipart();

readHeader protected

void readHeader(
    std::istream & istr
);

readMultipart protected

void readMultipart(
    std::istream & istr,
    PartHandler & handler
);

readPart protected

void readPart(
    std::istream & istr,
    const MessageHeader & header,
    PartHandler & handler
);

setRecipientHeaders protected

void setRecipientHeaders(
    MessageHeader & headers
) const;

writeEncoded protected

void writeEncoded(
    std::istream & istr,
    std::ostream & ostr,
    ContentTransferEncoding encoding
) const;

writeHeader protected

void writeHeader(
    const MessageHeader & header,
    std::ostream & ostr
) const;

writeMultipart protected

void writeMultipart(
    MessageHeader & header,
    std::ostream & ostr
) const;

writePart protected

void writePart(
    MultipartWriter & writer,
    const Part & part
) const;

Variables

CTE_7BIT static

static const std::string CTE_7BIT;

CTE_8BIT static

static const std::string CTE_8BIT;

CTE_BASE64 static

static const std::string CTE_BASE64;

CTE_QUOTED_PRINTABLE static

static const std::string CTE_QUOTED_PRINTABLE;

EMPTY_HEADER static

static const std::string EMPTY_HEADER;

HEADER_BCC static

static const std::string HEADER_BCC;

HEADER_CC static

static const std::string HEADER_CC;

HEADER_CONTENT_DISPOSITION static

static const std::string HEADER_CONTENT_DISPOSITION;

HEADER_CONTENT_ID static

static const std::string HEADER_CONTENT_ID;

HEADER_CONTENT_TRANSFER_ENCODING static

static const std::string HEADER_CONTENT_TRANSFER_ENCODING;

HEADER_CONTENT_TYPE static

static const std::string HEADER_CONTENT_TYPE;

HEADER_DATE static

static const std::string HEADER_DATE;

HEADER_FROM static

static const std::string HEADER_FROM;

HEADER_MIME_VERSION static

static const std::string HEADER_MIME_VERSION;

HEADER_SUBJECT static

static const std::string HEADER_SUBJECT;

HEADER_TO static

static const std::string HEADER_TO;

TEXT_PLAIN static

static const std::string TEXT_PLAIN;