Networking Tools: Thread-hot Internet Classes (int library)
| connect() dele() list() noop() |
pass() pop3StreamFilter() quit() retr() |
rset() stat() top() uidl() |
user() |
#include <rw/toolpro/pop3.h> RWIPop3Client client;
thr, net, int, tls (and possibly std)
RWIPop3Client provides low-level access to the POP3 client-side protocol. The names of the methods parallel the names of the protocol commands. The RWIPop3Client class maintains a finite state machine to enforce correct POP3 protocol action ordering. In the case of misordered method invocation, an exception is thrown.
Each client method returns an RWIOUResult whose redeemable is a particular type of RWIPop3Reply. RWIPop3Reply and its subclasses RWIPop3ConnReply, RWIPop3StatReply, and RWIPop3DataReply contain encapsulations of standard POP3 protocol reply messages. The derived classes of RWIPop3Reply return additional information specific to that type of protocol reply.
All multi-line POP3 responses are provided on a portal available by calling RWIPop3DataReply::portal(). These lines are bounded by the octet pair <cr><lf>, and the final line of a multi-line response consists of the triplet <period><cr><lf>.
RWIPop3Client objects are lightweight. They are implemented using the interface-implementation pattern. The RWIPop3Client 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/pop3.h>
void
main()
{
RWWinSockInfo info;
RWIPop3Client client;
RWIPop3ConnReply cReply; // connection reply
RWIPop3Reply reply; // general reply
RWIPop3StatReply sReply; // status reply
RWIPop3DataReply 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();
(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;
}
}
RWIPop3Client();
Constructs a default RWIPop3Client. Use the connect method to connect to a POP3 server.
RWIOUResult<RWIPop3ConnReply> connect(const RWCString& host, int port=110);
Establishes a connection to a POP3 server. The host argument is an IP address or host domain name of the POP3 server. The port argument is the server socket port that the POP3 service is attached to, typically 110. A successful reply is normally +OK. Usually the next action to perform is the user action. If the method fails, it throws an RWIProtocolClientErr exception.
RWIOUResult<RWIPop3Reply> 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.
RWIOUResult<RWIPop3DataReply> list(int message=0);
Invokes the LIST command on an open POP3 mail account. Returns an RWIOUResult with a redeemable RWIPop3DataReply. The RWIOUResult is set invalid if the call is unsuccessful.
This method has two modes. The socket portal associated with the redeemable return value has different behavior depending on the mode. The default mode (see below) provides data on the socket portal, but if you request a list for an individual message, data is returned directly and not provided to the portal. If you attempt to read from the portal when no data is available, the reading thread blocks indefinitely.
To obtain a list of all messages, invoke the method with the default argument zero. The server provides the socket portal with 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>.
If the method is invoked with a legal message index, a single POP3 scan listing is returned. 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.
RWIOUResult<RWIPop3Reply> noop();
Invokes the NOOP command on an open POP3 mail account. A successful reply is normally +OK.
RWIOUResult<RWIPop3Reply> 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. Usually the next action performed would be a call to the STAT, LIST, RETR, DELE, TOP, or NOOP actions.
RWIOUResult<RWIPop3Reply> 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.
RWIOUResult<RWIPop3DataReply> 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 RWIOUResult with a redeemable RWIPop3DataReply. An RWIPop3DataReply object contains a socket portal to 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. When this sequence is received, the message is complete. A successful reply is normally +OK.
RWIOUResult<RWIPop3Reply> rset();
Invokes the RSET command on an open POP3 mail account, which unmarks all messages marked as deleted. A successful reply is normally +OK.
RWIOUResult<RWIPop3StatReply> 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 RWIOUResult with a redeemable RWIPop3StatReply. RWIPop3StatReply provides messages() to show the number of messages in the mail drop and octets() to show the total number of octets.
RWIOUResult<RWIPop3DataReply> 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 RWIOUResult with a redeemable RWIPop3DataReply. An RWIPop3DataReply 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.
RWIOUResult<RWIPop3DataReply> uidl(int message=0);
Invokes the UIDL command on an open POP3 mail account. It requests that a unique message ID be returned for a particular message (indexed by message) or for all messages (if message is zero, which is the default).
This method has two modes. The socket portal associated with the redeemable return value has different behavior depending on the mode. The default mode (see below) provides data on the socket portal, but if you request a unique message ID for an individual message, data is returned directly and not provided to the portal. If you attempt to read from the portal when no data is available, the reading thread blocks indefinitely.
To obtain unique message IDs for all messages, invoke the method with the default argument zero. 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>.
If the method is invoked with a legal message ID, a single POP3 scan listing is returned. The message ID, formatted as for the multiple list command, is available by calling additionalData() on the redeemable returned by the command. No data is available at the socket portal.
RWIOUResult<RWIPop3Reply> 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. Usually the next action to perform is the PASS action.
RWBoolean 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.
©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.