RWSmtpClient

Module:  Internet Protocols Module   Package:  SMTP

Does not inherit

• Local Index
• Header File
• Description
• Example
• Enumeration
• Public Constructor
• Public Member Functions

Members

auth() authenticationType connect() dataClose() dataOpen()

ehlo() expn() getTimeout() helo() mail()

noop() quit() rcpt() rset() RWSmtpClient()

setTimeout() vrfy()

#include <rw/smtp/RWSmtpClient.h>

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 RWTIOUResults 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.

#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.portal().sendAtLeast("We've got a problem... \n");
        dReply.portal().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) {
        cout << "Error : " << m.why() << endl;
    }
    return 0;
}

enum authenticationType {
     CRAM_MD5
};

SMTP authentication method.

RWSmtpClient();

Uses connect() to establish a connection with an SMTP server.

RWTIOUResult<RWSmtpReply>
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>
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>
dataClose();

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

RWTIOUResult<RWSmtpDataReply>
dataOpen();

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 RWSmtpReply portal method.

RWTIOUResult<RWSmtpReply>
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>
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
getTimeout(void) const;

Retrieves the current network timeout value (in milliseconds).

RWTIOUResult<RWSmtpReply>
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>
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>
noop(); 

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>
quit();

Closes the connection to the SMTP server.

RWTIOUResult<RWSmtpReply>
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>
rset();

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
setTimeout(unsigned long timeout);

Sets the network timeout value (in milliseconds).

RWTIOUResult<RWSmtpReply>
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.

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.