RWSmtpClient Class Reference

Enables low-level access to the SMTP client-side protocol. More...

#include <rw/smtp/RWSmtpClient.h>

Public Types
enum	authenticationType { CRAM_MD5 }

Public Member Functions
	RWSmtpClient (void)
RWTIOUResult< RWSmtpReply >	auth (RWCString const &user, RWCString const &passwd, authenticationType)
RWTIOUResult< RWSmtpReply >	connect (const RWSockAddrBase &address)
RWTIOUResult< RWSmtpReply >	dataClose (void)
RWTIOUResult< RWSmtpDataReply >	dataOpen (void)
RWTIOUResult< RWSmtpReply >	ehlo (const RWCString &localMachine)
RWTIOUResult< RWSmtpReply >	expn (const RWCString &who)
unsigned long	getTimeout (void) const
RWTIOUResult< RWSmtpReply >	helo (const RWCString &localMachine)
RWTIOUResult< RWSmtpReply >	mail (const RWCString &from)
RWTIOUResult< RWSmtpReply >	noop (void)
RWTIOUResult< RWSmtpReply >	quit (void)
RWTIOUResult< RWSmtpReply >	rcpt (const RWCString &to)
RWTIOUResult< RWSmtpReply >	rset (void)
void	setTimeout (unsigned long timeout)
RWTIOUResult< RWSmtpReply >	vrfy (const RWCString &who)

Detailed Description

RWSmtpClient enables low-level access to the SMTP client-side protocol. The names of the methods parallel the names of the protocol actions. An RWSmtpClient object maintains a finite state machine to enforce correct SMTP protocol action ordering. In the case of misordered method invocation, an RWProtocolClientCmdSequenceError exception is thrown.

All client methods return RWTIOUResult instances that are redeemable for a particular type of RWSmtpReply. RWSmtpReply and its subclass RWSmtpDataReply contain an encapsulation of standard SMTP protocol reply messages. RWSmtpDataReply returns additional data-related information.

RWSmtpClient objects are lightweight. They are implemented using the interface-implementation idiom. The RWSmtpClient 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/RWPortalIStream.h>
#include <rw/network/RWWinSockInfo.h>

#include <rw/smtp/RWSmtpClient.h>

int main()
{
    RWWinSockInfo info;

    RWSmtpClient client;    // SMTP client object
    RWSmtpReply reply;      // SMTP general reply
    RWSmtpDataReply dReply; // SMTP data reply

    try {
        // Connect to our SMTP server
        reply = client.connect("smtp.roguewave.com");

        // Say hello from the local machine
        reply = client.helo("tsunami");

        // Mail From: and To:
        reply = client.mail("customer.roguewave.com");
        reply = client.rcpt("support.roguewave.com");

        // Send a help message
        dReply = client.dataOpen();
        dReply.getPortal().sendAtLeast("We've got a problem... \n");
        dReply.getPortal().sendAtLeast("Please help immediately");

        // Indicate it's the end of the message
        reply = client.dataClose();

        // Send more messages, if you like

        // Finally shut down the connection
        reply = client.quit();
    }
    catch (const RWxmsg& m) {
        std::cout << "Error : " << m.why() << std::endl;
    }
    return 0;
}

Member Enumeration Documentation

enum RWSmtpClient::authenticationType

SMTP authentication method.

Enumerator
CRAM_MD5	Use the CRAM-MD5 authentication mechanism (see RFC 2195)

Constructor & Destructor Documentation

RWSmtpClient::RWSmtpClient

(

void

)

Default constructor.

Member Function Documentation

RWTIOUResult<RWSmtpReply> RWSmtpClient::auth	(	RWCString const &	user,
		RWCString const &	passwd,
		authenticationType
	)

Performs authentication according to RFC 2554 and RFC 4422. The only authentication mechanism supported is CRAM-MD5 (see RFC 2195).

RWTIOUResult<RWSmtpReply> RWSmtpClient::connect

(

const RWSockAddrBase &

address

)

Establishes a connection with an SMTP server. The address argument is the address of the SMTP server. A successful reply is normally in the 2XX family.

RWTIOUResult<RWSmtpReply> RWSmtpClient::dataClose

(

void

)

Closes the body of the mail message opened with dataOpen(). This method writes the body termination sequence <period><cr><lf>.

RWTIOUResult<RWSmtpDataReply> RWSmtpClient::dataOpen

(

void

)

Performs the protocol DATA action. The DATA action informs the SMTP server that the following data should be considered the body of the message. By definition, the body of the message is terminated by a line containing only <period><cr><lf>. The dataClose() method inserts this sequence into the data stream, so it is your responsibility to ensure that the data termination sequence is not contained within the body of the message.

You can use the global function rwAddPeriods() to help you format the message. For more information, see rwAddPeriods(). A successful reply is normally in the 3XX family.

The method returns an RWTIOUResult with a redeemable RWSmtpReply. Data (message body) can then be written to the socket portal that is returned from the RWSmtpDataReply getPortal() method.

RWTIOUResult<RWSmtpReply> RWSmtpClient::ehlo

(

const RWCString &

localMachine

)

Performs the protocol EHLO action, which is just like HELP, but the server's response text provides computer-readable information about the server's abilities. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWSmtpReply> RWSmtpClient::expn

(

const RWCString &

who

)

Performs the protocol EXPN action. The EXPN action is similar to the VRFY action, except that some servers expand the email address if it is a mailing list. The who argument is the email address of the mail recipient. A successful reply is normally in the 2XX family if the email address is known by the destination. The RWCString should contain 7-bit US-ASCII data.

unsigned long RWSmtpClient::getTimeout

(

void

)

const

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWSmtpReply> RWSmtpClient::helo

(

const RWCString &

localMachine

)

Performs the protocol HELO action. The HELO action informs the SMTP server of the name of the client machine sending the mail, specified as the localMachine argument. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWSmtpReply> RWSmtpClient::mail

(

const RWCString &

from

)

Performs the protocol MAIL action. The from argument is the email address of the mail sender. The MAIL action sends the email address to the SMTP server. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWSmtpReply> RWSmtpClient::noop

(

void

)

Performs the protocol NOOP action. The NOOP action is often used to test whether the established connection to the SMTP server is still valid before the client sends a message. A successful reply is normally in the 2XX family.

RWTIOUResult<RWSmtpReply> RWSmtpClient::quit

(

void

)

Closes the connection to the SMTP server.

RWTIOUResult<RWSmtpReply> RWSmtpClient::rcpt

(

const RWCString &

to

)

Performs the protocol RCPT action. The to argument is the email address of the recipient. The RCPT action sends the email address to the SMTP server. A successful reply is normally in the 2XX family. The RWCString should contain 7-bit US-ASCII data.

RWTIOUResult<RWSmtpReply> RWSmtpClient::rset

(

void

)

Performs the protocol RSET action that takes the internal state machine and connection back to the initially connected state. Your application should call the HELO action next. A successful reply is normally in the 2XX family.

void RWSmtpClient::setTimeout

(

unsigned long

timeout

)

Sets the network timeout value (in milliseconds).

RWTIOUResult<RWSmtpReply> RWSmtpClient::vrfy

(

const RWCString &

who

)

Performs the protocol VRFY action. The who argument specifies the email recipient. The VRFY action requests confirmation of the validity of the email recipient without sending a message. A successful reply is normally in the 2XX family if the email address is known by the destination. The RWCString should contain 7-bit US-ASCII data.