RWSmtpAgent

Module:  Internet Protocols Module   Package:  SMTP

RWSmtpAgentRWAgent

• Local Index
• Header File
• Description
• Example
• Public Enum
• Public Constructors
• Public Member Functions

Members

dataClose() getTimeout()

headerMode RWSmtpAgent()

send() setTimeout()

#include <rw/smtp/RWSmtpAgent.h>

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.

#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) {
        cout << "Error : " << m.why() << endl;
    }
    return 0;
}

enum headerMode { DEFAULT_HEADERS, NO_HEADERS };

Enumerates whether or not default header information should be included in a mail message. DEFAULT_HEADERS includes the To: and From: headers in the header section of the message. NO_HEADERS does not include this information. In the NO_HEADERS case, however, almost all SMTP servers include the From: header automatically. Applications can include the information at the beginning of a mail message.

RWSmtpAgent();

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(const RWSockAddrBase& address, 
            const RWCString& 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.

RWTIOUResult<bool>
dataClose();

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

Retrieves the current network timeout value (in milliseconds).

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

Sets the network timeout value (in milliseconds).

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