RWSmtpAgent Class Reference

Sends data to a server via the SMTP protocol. More...

#include <rw/smtp/RWSmtpAgent.h>

Inherits RWAgent.

Public Types
enum	headerMode { DEFAULT_HEADERS, NO_HEADERS }

Public Member Functions
	RWSmtpAgent (void)
	RWSmtpAgent (const RWSockAddrBase &address, const RWCString &localHost="localhost")
RWTIOUResult< bool >	dataClose (void)
unsigned long	getTimeout (void) const
RWTIOUResult< RWSocketPortal >	send (const RWCString &from, const RWCString &to, headerMode h=RWSmtpAgent::DEFAULT_HEADERS)
void	setTimeout (unsigned long timeout)

Detailed Description

RWSmtpAgent sends data to a server via the SMTP protocol. It includes more of the details of the SMTP protocol than the RWSmtpClient class, but has less flexibility.

RWSmtpAgent performs actions in a transaction-based model rather than the connection-based model of the RWSmtpClient. Its methods interact with an SMTP server by connecting, performing the requested action, and disconnecting. Multiple transactions may be performed before the agent object is destroyed. The destructor cleans up resources.

RWSmtpAgent objects are lightweight. They are implemented using the interface-implementation idiom. The RWSmtpAgent is a handle to an implementation that performs the protocol interaction.

Example

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

#include <rw/network/RWSocketPortal.h>
#include <rw/network/RWWinSockInfo.h>

#include <rw/smtp/RWSmtpAgent.h>

int main()
{
    RWWinSockInfo info;

    try {
        // Construct an agent to talk with our known
        // SMTP server
        RWSmtpAgent agent("smtp.roguewave.com");

        // Force the RWTIOUResult<RWSocketPortal> to redeem
        // immediately for our portal.
        RWSocketPortal portal =
           agent.send("fred@roguewave.com",
                      "bill@anywhere.com");

        // Send our one line message, on the way out.
        portal.sendAtLeast("I've gone to the beach.");

        // Close up the agent and go to the beach...
        // Force the RWTIOUResult<bool> to
        // redeem immediately
        // for the result.
        bool result = agent.dataClose();
    }
    catch (const RWxmsg& m) {
        std::cout << "Error : " << m.why() << std::endl;
    }
    return 0;
}

Member Enumeration Documentation

enum RWSmtpAgent::headerMode

Enumerates whether or not default header information should be included in a mail message.

Enumerator
DEFAULT_HEADERS	Includes the To and From headers in the header section of the message.
NO_HEADERS	Does not include the To and From headers in the header section of the message. Almost all SMTP servers include the From header automatically. Applications can include the information at the beginning of a mail message.

Constructor & Destructor Documentation

RWSmtpAgent::RWSmtpAgent

(

void

)

Constructs a default invalid RWSmtpAgent object. Redemption of an RWTIOUResult from any call on a default agent throws an exception. Use the assignment operator to initialize a default RWSmtpAgent.

RWSmtpAgent::RWSmtpAgent	(	const RWSockAddrBase &	address,
		const RWCString &	localHost = "localhost"
	)

Constructs an RWSmtpAgent object that is ready to use in a subsequent call to the send() method. The address parameter is the address of the SMTP server. The localHost argument is the name of the client host used to greet the SMTP server. Generally this is the name of the local host, which is the default. The RWCString should contain 7-bit US-ASCII data.

Member Function Documentation

RWTIOUResult<bool> RWSmtpAgent::dataClose

(

void

)

Closes the body of a mail message opened with the send() method. This method writes the body termination sequence <period><cr><lf> to the available data socket portal to indicate the end of the message.

unsigned long RWSmtpAgent::getTimeout

(

void

)

const

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWSocketPortal> RWSmtpAgent::send	(	const RWCString &	from,
		const RWCString &	to,
		headerMode	h = RWSmtpAgent::DEFAULT_HEADERS
	)

Returns an RWTIOUResult with a redeemable RWSocketPortal. You can use the RWSocketPortal that is returned to complete the data portion of the protocol transfer. The from argument is a string representing the RFC822-compliant email address of the sender. The to argument is a string representing the RFC822-compliant e-mail address of the recipient. The h argument controls the inclusion of default header information in the message. If this value is the default DEFAULT_HEADERS, then To: and From: headers are included automatically in the data stream before the portal becomes available. Almost all SMTP servers include the From header in the email.

Including default headers does not prevent the application from including other headers (for example, a subject header), but it is an easy way to include the minimum customary header information.

The message sent through the socket portal must be formatted according to the SMTP specification: Leading periods on a line must be doubled except for the "end of message" signal, which is handled by the dataClose() method. You can use the global function rwAddPeriods() to help you format the message. For more information, see rwAddPeriods().

After a successful data transfer using the returned RWSocketPortal, your application must call the dataClose() method to complete the body of the mail message. The RWCString should contain 7-bit US-ASCII data.

void RWSmtpAgent::setTimeout

(

unsigned long

timeout

)

Sets the network timeout value (in milliseconds).