class Poco::Net::SMTPClientSession

Overview

This class implements an Simple Mail Transfer Protocol (SMTP, RFC 2821) client for sending e-mail messages. More…

#include <SMTPClientSession.h>

class SMTPClientSession
{
public:
    // typedefs

    typedef std::vector<std::string> Recipients;

    // enums

    enum
    {
        SMTP_PORT = 25,
    };

    enum LoginMethod;

    // construction

    SMTPClientSession(const StreamSocket& socket);

    SMTPClientSession(
        const std::string& host,
        Poco::UInt16 port = SMTP_PORT
        );

    // methods

    void
    setTimeout(const Poco::Timespan& timeout);

    Poco::Timespan
    getTimeout() const;

    void
    login(const std::string& hostname);

    void
    login();

    void
    login(
        const std::string& hostname,
        LoginMethod loginMethod,
        const std::string& username,
        const std::string& password
        );

    void
    login(
        LoginMethod loginMethod,
        const std::string& username,
        const std::string& password
        );

    void
    open();

    void
    close();

    void
    sendMessage(const MailMessage& message);

    void
    sendMessage(
        const MailMessage& message,
        const Recipients& recipients
        );

    void
    sendMessage(std::istream& istr);

    int
    sendCommand(
        const std::string& command,
        std::string& response
        );

    int
    sendCommand(
        const std::string& command,
        const std::string& arg,
        std::string& response
        );

    void
    sendAddresses(
        const std::string& from,
        const Recipients& recipients
        );

    void
    sendData();

protected:
    // enums

    enum
    {
        DEFAULT_TIMEOUT = 30000000,
    };

    enum StatusClass;

    // methods

    static
    bool
    isPositiveCompletion(int status);

    static
    bool
    isPositiveIntermediate(int status);

    static
    bool
    isTransientNegative(int status);

    static
    bool
    isPermanentNegative(int status);

    void
    login(
        const std::string& hostname,
        std::string& response
        );

    void
    loginUsingCRAMMD5(
        const std::string& username,
        const std::string& password
        );

    void
    loginUsingCRAMSHA1(
        const std::string& username,
        const std::string& password
        );

    void
    loginUsingCRAM(
        const std::string& username,
        const std::string& method,
        Poco::DigestEngine& hmac
        );

    void
    loginUsingLogin(
        const std::string& username,
        const std::string& password
        );

    void
    loginUsingPlain(
        const std::string& username,
        const std::string& password
        );

    void
    loginUsingXOAUTH2(
        const std::string& username,
        const std::string& password
        );

    DialogSocket&
    socket();
};

Detailed Documentation

This class implements an Simple Mail Transfer Protocol (SMTP, RFC 2821) client for sending e-mail messages.

Construction

SMTPClientSession(const StreamSocket& socket)

Creates the SMTPClientSession using the given socket, which must be connected to a SMTP server.

SMTPClientSession(
    const std::string& host,
    Poco::UInt16 port = SMTP_PORT
    )

Creates the SMTPClientSession using a socket connected to the given host and port.

Methods

void
setTimeout(const Poco::Timespan& timeout)

Sets the timeout for socket read operations.

Poco::Timespan
getTimeout() const

Returns the timeout for socket read operations.

void
login(const std::string& hostname)

Greets the SMTP server by sending a EHLO command with the given hostname as argument.

If the server does not understand the EHLO command, a HELO command is sent instead.

Throws a SMTPException in case of a SMTP-specific error, or a NetException in case of a general network communication failure.

void
login()

Calls login(hostname) with the current host name.

void
login(
    const std::string& hostname,
    LoginMethod loginMethod,
    const std::string& username,
    const std::string& password
    )

Logs in to the SMTP server using the given authentication method and the given credentials.

void
login(
    LoginMethod loginMethod,
    const std::string& username,
    const std::string& password
    )

Logs in to the SMTP server using the given authentication method and the given credentials.

void
open()

Reads the initial response from the SMTP server.

Usually called implicitly through login(), but can also be called explicitly to implement different forms of SMTP authentication.

Does nothing if called more than once.

void
close()

Sends a QUIT command and closes the connection to the server.

Throws a SMTPException in case of a SMTP-specific error, or a NetException in case of a general network communication failure.

void
sendMessage(const MailMessage& message)

Sends the given mail message by sending a MAIL FROM command, a RCPT TO command for every recipient, and a DATA command with the message headers and content.

Using this function results in RCPT TO commands list generated from the recipient list supplied with the message itself.

Throws a SMTPException in case of a SMTP-specific error, or a NetException in case of a general network communication failure.

void
sendMessage(
    const MailMessage& message,
    const Recipients& recipients
    )

Sends the given mail message by sending a MAIL FROM command, a RCPT TO command for every recipient, and a DATA command with the message headers and content.

Using this function results in message header being generated from the supplied recipients list.

Throws a SMTPException in case of a SMTP-specific error, or a NetException in case of a general network communication failure.

void
sendMessage(std::istream& istr)

Sends the mail message from the supplied stream.

Content of the stream is copied without any checking. Only the completion status is checked and, if not valid, SMTPExcpetion is thrown.

int
sendCommand(
    const std::string& command,
    std::string& response
    )

Sends the given command verbatim to the server and waits for a response.

Throws a SMTPException in case of a SMTP-specific error, or a NetException in case of a general network communication failure.

int
sendCommand(
    const std::string& command,
    const std::string& arg,
    std::string& response
    )

Sends the given command verbatim to the server and waits for a response.

Throws a SMTPException in case of a SMTP-specific error, or a NetException in case of a general network communication failure.

void
sendAddresses(
    const std::string& from,
    const Recipients& recipients
    )

Sends the message preamble by sending a MAIL FROM command, and a RCPT TO command for every recipient.

Throws a SMTPException in case of a SMTP-specific error, or a NetException in case of a general network communication failure.

void
sendData()

Sends the message preamble by sending a DATA command.

Throws a SMTPException in case of a SMTP-specific error, or a NetException in case of a general network communication failure.