class Poco::Net::POP3ClientSession

Overview

This class implements an Post Office Protocol Version 3 (POP3, RFC 1939) client for receiving e-mail messages. More…

#include <POP3ClientSession.h>

class POP3ClientSession
{
public:
    // typedefs

    typedef std::vector<MessageInfo> MessageInfoVec;

    // enums

    enum
    {
        POP3_PORT = 110,
    };

    // structs

    struct MessageInfo;

    // construction

    POP3ClientSession(const StreamSocket& socket);

    POP3ClientSession(
        const std::string& host,
        Poco::UInt16 port = POP3_PORT
        );

    // methods

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

    Poco::Timespan
    getTimeout() const;

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

    void
    close();

    int
    messageCount();

    void
    listMessages(MessageInfoVec& messages);

    void
    retrieveMessage(
        int id,
        MailMessage& message
        );

    void
    retrieveMessage(
        int id,
        MailMessage& message,
        PartHandler& handler
        );

    void
    retrieveMessage(
        int id,
        std::ostream& ostr
        );

    void
    retrieveHeader(
        int id,
        MessageHeader& header
        );

    void
    deleteMessage(int id);

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

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

    bool
    sendCommand(
        const std::string& command,
        const std::string& arg1,
        const std::string& arg2,
        std::string& response
        );

protected:
    // methods

    static
    bool
    isPositive(const std::string& response);
};

Detailed Documentation

This class implements an Post Office Protocol Version 3 (POP3, RFC 1939) client for receiving e-mail messages.

Construction

POP3ClientSession(const StreamSocket& socket)

Creates the POP3ClientSession using the given socket, which must be connected to a POP3 server.

POP3ClientSession(
    const std::string& host,
    Poco::UInt16 port = POP3_PORT
    )

Creates the POP3ClientSession 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& username,
    const std::string& password
    )

Logs in to the POP3 server by sending a USER command followed by a PASS command.

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

void
close()

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

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

int
messageCount()

Sends a STAT command to determine the number of messages available on the server and returns that number.

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

void
listMessages(MessageInfoVec& messages)

Fills the given vector with the ids and sizes of all messages available on the server.

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

void
retrieveMessage(
    int id,
    MailMessage& message
    )

Retrieves the message with the given id from the server and stores the raw message content in the message’s content string, available with message.getContent().

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

void
retrieveMessage(
    int id,
    MailMessage& message,
    PartHandler& handler
    )

Retrieves the message with the given id from the server and stores it in message.

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

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

void
retrieveMessage(
    int id,
    std::ostream& ostr
    )

Retrieves the raw message with the given id from the server and copies it to the given output stream.

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

void
retrieveHeader(
    int id,
    MessageHeader& header
    )

Retrieves the message header of the message with the given id and stores it in header.

For this to work, the server must support the TOP command.

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

void
deleteMessage(int id)

Marks the message with the given ID for deletion.

The message will be deleted when the connection to the server is closed by calling close().

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

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

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

Returns true if the response is positive, false otherwise.

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

bool
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.

Returns true if the response is positive, false otherwise.

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

bool
sendCommand(
    const std::string& command,
    const std::string& arg1,
    const std::string& arg2,
    std::string& response
    )

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

Returns true if the response is positive, false otherwise.

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