SourcePro® 2023.1 |
SourcePro® API Reference Guide |
Enables low-level access to the POP3 client-side protocol. More...
#include <rw/pop3/RWPop3Client.h>
Public Member Functions | |
RWPop3Client (void) | |
RWTIOUResult< RWPop3ConnReply > | connect (const RWSockAddrBase &address) |
RWTIOUResult< RWPop3Reply > | dele (int message) |
unsigned long | getTimeout (void) const |
RWTIOUResult< RWPop3DataReply > | list (int message=0) |
RWTIOUResult< RWPop3Reply > | noop (void) |
RWTIOUResult< RWPop3Reply > | pass (const RWCString &password) |
RWTIOUResult< RWPop3Reply > | quit (void) |
RWTIOUResult< RWPop3DataReply > | retr (int message) |
RWTIOUResult< RWPop3Reply > | rset (void) |
void | setTimeout (unsigned long timeout) |
RWTIOUResult< RWPop3StatReply > | stat (void) |
RWTIOUResult< RWPop3DataReply > | top (int message, int lines) |
RWTIOUResult< RWPop3DataReply > | uidl (int message=0) |
RWTIOUResult< RWPop3Reply > | user (const RWCString &user) |
Related Functions | |
(Note that these are not member functions.) | |
bool | pop3StreamFilter (const RWCString &buffer) |
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.
RWPop3Client::RWPop3Client | ( | void | ) |
Constructs a default RWPop3Client.
RWTIOUResult<RWPop3ConnReply> RWPop3Client::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> RWPop3Client::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 RWPop3Client::getTimeout | ( | void | ) | const |
Retrieves the current network timeout value (in milliseconds).
RWTIOUResult<RWPop3DataReply> RWPop3Client::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:
<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 you attempt to read from the portal when no data is available, the reading thread blocks indefinitely.
RWTIOUResult<RWPop3Reply> RWPop3Client::noop | ( | void | ) |
Invokes the NOOP
command on an open POP3 mail account. A successful reply is normally +OK
.
RWTIOUResult<RWPop3Reply> RWPop3Client::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> RWPop3Client::quit | ( | void | ) |
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> RWPop3Client::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> RWPop3Client::rset | ( | void | ) |
Invokes the RSET
command on an open POP3 mail account, which unmarks all messages marked as deleted. A successful reply is normally +OK
.
void RWPop3Client::setTimeout | ( | unsigned long | timeout | ) |
Sets the network timeout value (in milliseconds).
RWTIOUResult<RWPop3StatReply> RWPop3Client::stat | ( | void | ) |
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> RWPop3Client::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> RWPop3Client::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 getText() 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> RWPop3Client::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.
|
related |
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 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 © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved. |