RWPop3Agent Class Reference

Enables basic POP3 mail access, with more details of the POP3 protocol than the RWPop3Client class, but less flexibility. More...

#include <rw/pop3/RWPop3Agent.h>

Inherits RWAgent.

Public Member Functions
	RWPop3Agent (void)
	RWPop3Agent (const RWSockAddrBase &address, const RWCString &user, const RWCString &password)
RWTIOUResult< RWSocketPortal >	getMessage (int messageIndex)
RWTIOUResult< int >	getMessageCount (void)
unsigned long	getTimeout (void) const
RWTIOUResult< RWPop3Reply >	removeMessage (int messageIndex)
void	setTimeout (unsigned long timeout)

Detailed Description

RWPop3Agent enables basic POP3 mail access. It includes more of the details of the POP3 protocol than the RWPop3Client class, but has less flexibility.

RWPop3Agent performs actions in a transaction-based model (contrast with the connection-based model of the RWPop3Client). Its methods interact with the server by connecting (if not already connected) and then performing the requested actions. Unlike other thread-hot Internet agent classes, such as RWFtpAgent, class RWPop3Agent remains connected between transactions because POP3 relies on transient, connection-based information. Multiple transactions may be performed before the object is destroyed. The destructor of the agent disconnects from the server and cleans up its own data.

RWPop3Agent objects are lightweight. They are implemented using the interface-implementation idiom. The RWPop3Agent 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/util.h>
#include <rw/pop3/RWPop3Agent.h>

int
main()
{
    RWWinSockInfo info;

    try {
        // Create an agent to talk with our POP3 server.
        RWPop3Agent agent("mail.roguewave.com",
                          "account",
                          "password");

        // Get the number of messages in our POP3 mail drop
        int n = agent.messages();

        // If we have at least one, then go get it and
        // display on the screen.
        if (n>0) {
            // Force the RWTIOUResult<RWSocketPortal> to redeem
            // immediately for our portal.
            RWSocketPortal p = agent.get(1);

            {
                 RWPortalIStream istrm(p);
                 RWCString text;
                 bool endOfMessage = false;

                 // Read the lines in the message until
                 // the end of message marker
                 // <period><cr><lf>
                 do {
                    // Let RWCString do the hard work
                    text.readLine(istrm);

                    // Remove <cr><lf>
                    text = rwNormalizeLine(text);
                    if (text==".")
                       endOfMessage = true;
                    else
                       std::cout << text << std::endl;
                } while (!endOfMessage);

            } // stream scope
        }
    }
    catch (const RWxmsg& m) {
        std::cout << "Error : " << m.why() << std::endl;
    }
    return 0;
}

Constructor & Destructor Documentation

RWPop3Agent::RWPop3Agent

(

void

)

Constructs a default invalid RWPop3Agent. Redemption of an RWTIOUResult from any call on a default agent throws an exception. Use the assignment operator to initialize a default RWPop3Agent object.

RWPop3Agent::RWPop3Agent	(	const RWSockAddrBase &	address,
		const RWCString &	user,
		const RWCString &	password
	)

Constructs an RWPop3Agent that is ready to use in subsequent, transactional calls. The address argument is the address of the POP3 server. The user and password arguments are the user and password to use during the POP3 login negotiation sequence. The RWCString should contain 7-bit US-ASCII data.

Member Function Documentation

RWTIOUResult<RWSocketPortal> RWPop3Agent::getMessage

(

int

messageIndex

)

Opens a data connection to a specified message on the POP3 server. It returns an RWTIOUResult with a redeemable RWSocketPortal. The RWSocketPortal that is returned is a socket portal to the data communication channel used to complete the data (message retrieval) portion of the protocol transfer. The messageIndex argument is the message number of the requested message.

RWTIOUResult<int> RWPop3Agent::getMessageCount

(

void

)

Returns an RWTIOUResult with a redeemable int. The int that is returned is a count of the waiting messages in the specified mail drop.

unsigned long RWPop3Agent::getTimeout

(

void

)

const

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWPop3Reply> RWPop3Agent::removeMessage

(

int

messageIndex

)

Returns an RWTIOUResult with a redeemable RWPop3Reply that contains an error if the method failed. The method deletes a message whose index is messageIndex. Your application should not use messageIndex again.

void RWPop3Agent::setTimeout

(

unsigned long

timeout

)

Sets the network timeout value (in milliseconds).