RWPop3Client Class Reference

Enables low-level access to the POP3 client-side protocol. More...

#include <rw/pop3/RWPop3Client.h>

Public Member Functions
	RWPop3Client (void)
RWTIOUResult< RWPop3ConnReply >	connect (const RWSockAddrBase &address)
RWTIOUResult< RWPop3Reply >	dele (int message)
unsigned long	getTimeout (void) const
RWTIOUResult< RWPop3DataReply >	list (int message=0)
RWTIOUResult< RWPop3Reply >	noop (void)
RWTIOUResult< RWPop3Reply >	pass (const RWCString &password)
RWTIOUResult< RWPop3Reply >	quit (void)
RWTIOUResult< RWPop3DataReply >	retr (int message)
RWTIOUResult< RWPop3Reply >	rset (void)
void	setTimeout (unsigned long timeout)
RWTIOUResult< RWPop3StatReply >	stat (void)
RWTIOUResult< RWPop3DataReply >	top (int message, int lines)
RWTIOUResult< RWPop3DataReply >	uidl (int message=0)
RWTIOUResult< RWPop3Reply >	user (const RWCString &user)

Related Functions
(Note that these are not member functions.)
bool	pop3StreamFilter (const RWCString &buffer)

Detailed Description

RWPop3Client enables low-level access to the POP3 client-side protocol. The names of its methods parallel the names of the protocol commands. The RWPop3Client class maintains a finite state machine to enforce correct POP3 protocol action ordering. In the case of misordered method invocation, an RWProtocolClientCmdSequenceError exception is thrown.

Each client method returns an RWTIOUResult whose redeemable is a particular type of RWPop3Reply. RWPop3Reply and its subclasses – RWPop3ConnReply, RWPop3StatReply, and RWPop3DataReply – contain encapsulations of standard POP3 protocol reply messages. The derived classes of RWPop3Reply return additional information specific to that type of protocol reply.

All multi-line POP3 responses are provided on a portal returned from RWPop3DataReply::getPortal(). These lines are bounded by the octet pair <cr><lf>. The final line of a multi-line response consists of the triplet <period><cr><lf>.

RWPop3Client objects are lightweight. They are implemented using the interface-implementation idiom. The RWPop3Client is a handle to an implementation that performs the protocol interaction.

Example

#include <rw/rstream.h>
#include <rw/cstring.h>

#include <rw/network/RWSocketPortal.h>
#include <rw/network/RWPortalIStream.h>
#include <rw/network/RWWinSockInfo.h>

#include <rw/pop3/RWPop3Client.h>

#include <rw/internet/util.h>

int main()
{
    RWWinSockInfo info;

    RWPop3Client client;
    RWPop3ConnReply cReply;  // connection reply
    RWPop3Reply reply;       // general reply
    RWPop3StatReply sReply;  // status reply
    RWPop3DataReply dReply;  // data reply

    try {
        // Establish a connection to our POP3 server
        cReply = client.connect("mail.roguewave.com");

        // create a login session
        reply = client.user("account");
        reply = client.pass("password");

        // scan the first 10 lines of each message in the
        // mail box
        sReply = client.stat();
        int n = sReply.messages();
        if(n > 0) {
            for (int I=0; I<n; I++) {
                dReply = client.top(I+1, 10);
                RWPortalIStream istrm(dReply.getPortal());
                RWCString text;
                do {
                   text =rwNormalizeLine(text.readLine(istrm));
                   if (text != ".") std::cout << text << std::endl;
                } while (text != ".");
            }
        }
    }
    catch (const RWxmsg& m) {
        std::cout << "Error : " << m.why() << std::endl;
    }
    return 0;
}

Constructor & Destructor Documentation

RWPop3Client::RWPop3Client

(

void

)

Constructs a default RWPop3Client.

Member Function Documentation

RWTIOUResult<RWPop3ConnReply> RWPop3Client::connect

(

const RWSockAddrBase &

address

)

Establishes a connection to a POP3 server. The address argument is the address of the POP3 server. A successful reply is normally +OK. An application usually calls the user() action next. If the method fails, it throws an RWProtocolClientError exception.

RWTIOUResult<RWPop3Reply> RWPop3Client::dele

(

int

message

)

Invokes the DELE command on an open POP3 mail drop, and marks the message as deleted. The message is not actually removed until a normal QUIT action is performed. However, the message is no longer available for use. A successful reply is normally +OK.

unsigned long RWPop3Client::getTimeout

(

void

)

const

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWPop3DataReply> RWPop3Client::list

(

int

message = 0

)

Invokes the LIST command on an open POP3 mail account. Returns an RWTIOUResult with a redeemable RWPop3DataReply. The RWTIOUResult is set invalid if the call is unsuccessful.

This method has two modes, and they determine the behavior of the socket portal associated with the redeemable return value:

• The default mode, where the argument is zero, returns a list of all messages on the socket portal. The server returns one scan listing per message in the mail box. Each scan listing contains a message index field, a size field, an optional further information field (deprecated in the POP3 RFC), and a trailing <cr><lf> to mark the end of the individual scan listing line. The fields are separated by a space. The message index is a string containing the base 10 representation of the index, and the size field is a string containing the base 10 representation of the number of octets contained in the message. The last line available from the socket portal consists of <period><cr><lf>.
• The second mode, where the argument is a legal message index, returns a single POP3 scan listing. The message id and size in octets, formatted as for the multiple list command, are available by calling getText() on the redeemable returned by the command. No data is available at the socket portal.

If you attempt to read from the portal when no data is available, the reading thread blocks indefinitely.

RWTIOUResult<RWPop3Reply> RWPop3Client::noop

(

void

)

Invokes the NOOP command on an open POP3 mail account. A successful reply is normally +OK.

RWTIOUResult<RWPop3Reply> RWPop3Client::pass

(

const RWCString &

password

)

Invokes the PASS command on an open POP3 mail account. It informs the POP3 server of the mail drop's password. A password is required to access the mail drop. A successful reply is normally +OK. An application would usually call the STAT, LIST, RETR, DELE, TOP, or NOOP actions next. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWPop3Reply> RWPop3Client::quit

(

void

)

Invokes the QUIT command on an open POP3 mail account, which shuts down the connection to the POP3 server. A successful reply is normally +OK.

RWTIOUResult<RWPop3DataReply> RWPop3Client::retr

(

int

message

)

Invokes the RETR command on an open POP3 mail account. It requests that a data connection be opened to the message indexed by message.

The method returns an RWTIOUResult with a redeemable RWPop3DataReply. An RWPop3DataReply object contains a socket portal that your application can use to complete the data portion of the protocol transfer. Reading from this portal returns the message data. POP3 mail messages are terminated by the data sequence <period><cr><lf> contained on a line by itself. A successful reply is normally +OK.

RWTIOUResult<RWPop3Reply> RWPop3Client::rset

(

void

)

Invokes the RSET command on an open POP3 mail account, which unmarks all messages marked as deleted. A successful reply is normally +OK.

void RWPop3Client::setTimeout

(

unsigned long

timeout

)

Sets the network timeout value (in milliseconds).

RWTIOUResult<RWPop3StatReply> RWPop3Client::stat

(

void

)

Invokes the STAT command on an open POP3 mail account. It returns the number of messages contained in the mail drop and the total number of octets that the mail messages consume. A successful reply is normally +OK.

The method returns an RWTIOUResult, which is redeemable for an RWPop3StatReply. RWPop3StatReply includes the getMessageCount() method, which returns the number of messages in the mail drop, and the getOctets() method, which returns the total number of octets.

RWTIOUResult<RWPop3DataReply> RWPop3Client::top	(	int	message,
		int	lines
	)

Invokes the TOP command on an open POP3 mail account. It requests that a data connection be opened to the message indexed by message, and it requests that lines number of message lines be returned. If the total number of lines in the message is fewer than lines, only the actual number of lines in the message are available.

The method returns an RWTIOUResult with a redeemable RWPop3DataReply. An RWPop3DataReply object contains a socket portal that is used to complete the data portion of the protocol transfer. Reading from this portal returns the message data. POP3 mail messages are terminated by the data sequence <period><cr><lf> contained on a line by itself. When this sequence is received, the message is complete. A successful reply is normally +OK.

RWTIOUResult<RWPop3DataReply> RWPop3Client::uidl

(

int

message = 0

)

Invokes the UIDL command on an open POP3 mail account. When message is zero (the default), it requests that unique message IDs be returned for all messages. When message is an index, it requests that a unique message ID be returned for a particular message.

The default mode returns data on the socket portal. The server provides the socket portal with one scan listing per message in the mail box. Each scan listing contains the message ID and a trailing <cr><lf> to mark the end of the individual scan listing line. The last line available from the socket portal consists of <period><cr><lf>.

When requesting a unique message ID for an individual message, data is returned directly and not provided to the portal. A single POP3 scan listing is returned. The message ID, formatted as for the multiple list command, is available by calling getText() on the redeemable returned by the command. No data is available at the socket portal.

If you attempt to read from the portal when no data is available, the reading thread blocks indefinitely.

RWTIOUResult<RWPop3Reply> RWPop3Client::user

(

const RWCString &

user

)

Invokes the USER command on an open POP3 mail account. It informs the POP3 server of the name of the mail drop to access. A successful reply is normally +OK. An application usually invokes the PASS action next. The RWCString should contain 7-bit US-ASCII data.

Friends And Related Function Documentation

bool pop3StreamFilter ( const RWCString &  buffer )

related

Recognizes an end-of-data condition, which is <period><cr><lf>, on an POP3 input stream. It can be passed as the filter argument to RWStreamCoupler::operator()() which takes a customized filter where it assists in coupling a POP3 message to an output stream. The RWCString should contain 7-bit US-ASCII data.