SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWPop3Agent Class Reference

Enables basic POP3 mail access, with more details of the POP3 protocol than the RWPop3Client class, but less flexibility. More...

#include <rw/pop3/RWPop3Agent.h>

Inherits RWAgent.

Public Member Functions

 RWPop3Agent (const RWSockAddrBase &address, const RWCString &user, const RWCString &password)
 
 RWPop3Agent (void)
 
RWTIOUResult< RWSocketPortalgetMessage (int messageIndex)
 
RWTIOUResult< int > getMessageCount (void)
 
unsigned long getTimeout (void) const
 
RWTIOUResult< RWPop3ReplyremoveMessage (int messageIndex)
 
void setTimeout (unsigned long timeout)
 

Detailed Description

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

Example
#include <rw/cstring.h>
#include <rw/rstream.h>
#include <rw/network/RWPortalIStream.h>
#include <rw/network/RWSocketPortal.h>
#include <rw/network/RWWinSockInfo.h>
#include <rw/pop3/RWPop3Agent.h>
#include <rw/pop3/util.h>
int main() {
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;
} else {
std::cout << text << std::endl;
}
} while (!endOfMessage);
} // stream scope
}
} catch (const RWxmsg& m) {
std::cout << "Error : " << m.why() << std::endl;
}
return 0;
}
Offers powerful and convenient facilities for manipulating strings.
Definition stdcstring.h:826
std::istream & readLine(std::istream &strm, bool skipWhite=true)
Enables basic POP3 mail access, with more details of the POP3 protocol than the RWPop3Client class,...
Definition RWPop3Agent.h:107
Socket implementation of a portal.
Definition RWSocketPortal.h:34
Provides a std::basic_istream that uses an RWPortal as its source of bytes.
Definition RWTPortalIStream.h:38
Initializes the Winsock DLL on Windows platforms.
Definition RWWinSockInfo.h:49
Base class for the hierarchy of exceptions in the Essential Tools Module.
Definition rwerr.h:57
virtual const char * why() const
RWCString rwNormalizeLine(const RWCString &text)

Constructor & Destructor Documentation

◆ RWPop3Agent() [1/2]

RWPop3Agent::RWPop3Agent ( void )

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() [2/2]

RWPop3Agent::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.

Member Function Documentation

◆ getMessage()

RWTIOUResult< RWSocketPortal > RWPop3Agent::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.

◆ getMessageCount()

RWTIOUResult< int > RWPop3Agent::getMessageCount ( void )

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

◆ getTimeout()

unsigned long RWPop3Agent::getTimeout ( void ) const

Retrieves the current network timeout value (in milliseconds).

◆ removeMessage()

RWTIOUResult< RWPop3Reply > RWPop3Agent::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.

◆ setTimeout()

void RWPop3Agent::setTimeout ( unsigned long timeout)

Sets the network timeout value (in milliseconds).

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.