class Poco::Net::MailMessage

Overview

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

#include <MailMessage.h>

class MailMessage: public Poco::Net::MessageHeader
{
public:
    // typedefs

    typedef std::vector<MailRecipient> Recipients;
    typedef std::vector<Part> PartVec;

    // enums

    enum ContentDisposition;
    enum ContentTransferEncoding;

    // structs

    struct Part;

    // fields

    static const std::string HEADER_SUBJECT;
    static const std::string HEADER_FROM;
    static const std::string HEADER_TO;
    static const std::string HEADER_CC;
    static const std::string HEADER_BCC;
    static const std::string HEADER_DATE;
    static const std::string HEADER_CONTENT_TYPE;
    static const std::string HEADER_CONTENT_TRANSFER_ENCODING;
    static const std::string HEADER_CONTENT_DISPOSITION;
    static const std::string HEADER_CONTENT_ID;
    static const std::string HEADER_MIME_VERSION;
    static const std::string EMPTY_HEADER;
    static const std::string TEXT_PLAIN;
    static const std::string CTE_7BIT;
    static const std::string CTE_8BIT;
    static const std::string CTE_QUOTED_PRINTABLE;
    static const std::string CTE_BASE64;

    // construction

    MailMessage(PartStoreFactory* pStoreFactory = 0);

    // methods

    void
    addRecipient(const MailRecipient& recipient);

    void
    setRecipients(const Recipients& recipient);

    const Recipients&
    recipients() const;

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

    const std::string&
    getSubject() const;

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

    const std::string&
    getSender() const;

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

    const std::string&
    getContent() const;

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

    void
    setContentType(const MediaType& mediaType);

    const std::string&
    getContentType() const;

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

    Poco::Timestamp
    getDate() const;

    bool
    isMultipart() const;

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

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

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

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

    const PartVec&
    parts() const;

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

    virtual
    void
    read(std::istream& istr);

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

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

protected:
    // methods

    void
    makeMultipart();

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

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

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

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

    void
    setRecipientHeaders(MessageHeader& headers) const;

    void
    readHeader(std::istream& istr);

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

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

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

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

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

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

Inherited Members

public:
    // typedefs

    typedef Poco::ListMap<std::string, std::string> HeaderMap;
    typedef HeaderMap::Iterator Iterator;
    typedef HeaderMap::ConstIterator ConstIterator;

    // methods

    NameValueCollection&
    operator=(const NameValueCollection& nvc);

    void
    swap(NameValueCollection& nvc);

    const std::string&
    operator[](const std::string& name) const;

    void
    set(
        const std::string& name,
        const std::string& value
        );

    void
    add(
        const std::string& name,
        const std::string& value
        );

    const std::string&
    get(const std::string& name) const;

    const std::string&
    get(
        const std::string& name,
        const std::string& defaultValue
        ) const;

    bool
    has(const std::string& name) const;

    ConstIterator
    find(const std::string& name) const;

    ConstIterator
    begin() const;

    ConstIterator
    end() const;

    bool
    empty() const;

    std::size_t
    size() const;

    void
    erase(const std::string& name);

    void
    clear();

    MessageHeader&
    operator=(const MessageHeader& messageHeader);

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

    virtual
    void
    read(std::istream& istr);

    int
    getFieldLimit() const;

    void
    setFieldLimit(int limit);

    bool
    hasToken(
        const std::string& fieldName,
        const std::string& token
        ) const;

    static
    void
    splitElements(
        const std::string& s,
        std::vector<std::string>& elements,
        bool ignoreEmpty = true
        );

    static
    void
    splitParameters(
        const std::string& s,
        std::string& value,
        NameValueCollection& parameters
        );

    static
    void
    splitParameters(
        const std::string::const_iterator& begin,
        const std::string::const_iterator& end,
        NameValueCollection& parameters
        );

    static
    void
    quote(
        const std::string& value,
        std::string& result,
        bool allowSpace = false
        );

Detailed Documentation

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.

Construction

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.

Methods

void
addRecipient(const MailRecipient& recipient)

Adds a recipient for the message.

void
setRecipients(const Recipients& recipient)

Clears existing and sets new recipient list for the message.

const Recipients&
recipients() const

Returns the recipients of the message.

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()).

const std::string&
getSubject() const

Returns the subject of the message.

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()).

const std::string&
getSender() const

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

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.

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.

void
setContentType(const std::string& mediaType)

Sets the content type for the message.

void
setContentType(const MediaType& mediaType)

Sets the content type for the message.

const std::string&
getContentType() const

Returns the content type for the message.

void
setDate(const Poco::Timestamp& dateTime)

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

Poco::Timestamp
getDate() const

Returns the value of the Date header.

bool
isMultipart() const

Returns true iff the message is a multipart message.

const PartVec&
parts() const

Returns const reference to the vector containing part stores.

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().

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().

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

Writes the mail message to the given output stream.

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.