RWPop3Client

Module:  Internet Protocols Module   Package:  POP3

Does not inherit

• Local Index
• Header File
• Description
• Example
• Public Constructor
• Public Member Functions
• Related Global Function

Members

connect() dele() getTimeout() list()

noop() pass() quit() retr()

rset() RWPop3Client() setTimeout() stat()

top() uidl() user()

Non-Members

pop3StreamFilter()

#include <rw/pop3/RWPop3Client.h>

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.

#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.portal());
                RWCString text;
                do {
                   text =rwNormalizeLine(text.readLine(istrm));
                   if (text != ".") cout << text << endl;
                } while (text != ".");
            }
        }
    }
    catch (const RWxmsg& m) {
        cout << "Error : " << m.why() << endl;
    }
    return 0;
}

RWPop3Client();

Uses the connect method to connect to a POP3 server.

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

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWPop3DataReply>
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 additionalData() 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>
noop(); 

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

RWTIOUResult<RWPop3Reply>
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>
quit();

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>
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>
rset();

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

void
setTimeout(unsigned long timeout);

Sets the network timeout value (in milliseconds).

RWTIOUResult<RWPop3StatReply>
stat();

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

bool
pop3StreamFilter(const RWCString& buffer);

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

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