RWIPop3Agent

RWIPop3AgentRWIAgent

• Module
• Data Type and Member Function Indexes
• Synopsis
• Required Libraries
• Description
• Example
• Public Constructors
• Public Member Functions

Networking Tools: Thread-hot Internet Classes (int library)

Member Functions

get()

messages()

remove()

#include <rw/toolpro/pop3a.h>
RWIPop3Agent agent;
RWIPop3Agent agent("mail.roguewave.com", "user",
                   "password");

thr, net, int, tls (and possibly std)

RWIPop3Agent provides basic POP3 mail accesses. It deals with more of the details of the POP3 protocol than the RWIPop3Client class, but provides less flexibility than the client class.

RWIPop3Agent performs actions in a transaction-based model rather than in the connection-based model of the RWIPop3Client. The 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 RWIFtpAgent and RWIHttpAgent, class RWIPop3Agent remains connected between transactions. This is 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.

RWIPop3Agent objects are lightweight. They are implemented using the interface-implementation pattern. The RWIPop3Agent itself is really a handle to an implementation that performs the protocol interaction.

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

#include <rw/toolpro/sockport.h>
#include <rw/toolpro/portstrm.h>
#include <rw/toolpro/winsock.h>

#include <rw/toolpro/util.h>
#include <rw/toolpro/pop3a.h>

void
main()
{
    RWWinSockInfo info;

    try {
        // Create an agent to talk with our POP3 server.
        RWIPop3Agent 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 IOUResult<RWSocketPortal> to redeem
            // immediately for our portal.
            RWSocketPortal p = agent.get(1);

            {        
                 RWPortalIStream istrm(p);
                 RWCString text;
                 RWBoolean 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;
    }
}

RWIPop3Agent();

Constructs a default invalid RWIPop3Agent. Using the default object results in an exception. Use the assignment operator to initialize a default RWIPop3Agent object.

RWIPop3Agent(const RWCString& host, const RWCString& user,
             const RWCString& password);

Constructs an RWIPop3Agent that is ready to use in subsequent, transactional calls. The host argument is the POP3 host running the POP3 server. The user and password arguments are the user and password to use during the POP3 login negotiation sequence.

RWIOUResult<RWSocketPortal>
get(int messageIndex);

Opens a data connection to a specified message on the POP3 server. It returns an RWIOUResult 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.

RWIOUResult<int>
messages();

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

RWIOUResult<RWIPop3Reply>
remove(int messageIndex);

Returns an RWIOUResult with a redeemable RWIPop3Reply, which contains an error if the method failed. The method deletes a message whose index is messageIndex. The messageIndex must not be used again.

©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.