RWPop3Agent

Module:  Internet Protocols Module   Package:  POP3

RWPop3AgentRWAgent

• Local Index
• Header File
• Description
• Example
• Public Constructors
• Public Member Functions

Members

getMessage() getMessageCount()

getTimeout() removeMessage()

RWPop3Agent() setTimeout()

#include <rw/pop3/RWPop3Agent.h>

RWPop3Agent enables basic POP3 mail accesses. 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.

#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;

                    if (text!=".") cout << text << endl;
                } while (!endOfMessage);

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

RWPop3Agent();

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

RWTIOUResult<RWSocketPortal>
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>
getMessageCount();

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
getTimeout(void) const;

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWPop3Reply>
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
setTimeout(unsigned long timeout);

Sets the network timeout value (in milliseconds).

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.