RWISmtpAgent

RWISmtpAgentRWIAgent

• Module
• Data Type and Member Function Indexes
• Synopsis
• Required Libraries
• Description
• Example
• Public Enums
• Public Constructors
• Public Member Functions

Networking Tools: Thread-hot Internet Classes (int library)

Data Types

headerMode

Member Functions

dataClose()

send()

#include <rw/toolpro/smtpa.h>
RWISmtpAgent agent;
RWISmtpAgent agent("mail.roguewave.com");

thr, net, int, tls (and possibly std)

RWISmtpAgent is used to send data to a server via the SMTP protocol. It deals with more of the details of the SMTP protocol than the RWISmtpClient class, but provides less flexibility.

RWISmtpAgent performs actions in a transaction-based model rather than the connection-based model of the RWISmtpClient. The 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. Finally, the destructor cleans up resources.

RWISmtpAgent objects are lightweight. They are implemented using the interface-implementation pattern. The RWISmtpAgent itself is really a handle to an implementation that performs the protocol interaction.

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

#include <rw/toolpro/sockport.h>
#include <rw/toolpro/portstrm.h>
#include <rw/toolpro/winsock.h>

#include <rw/toolpro/smtpa.h>

void
main()
{
    RWWinSockInfo info;

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

        // Force the RWIOUResult<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 RWIOUResult<RWBoolean> to 
        // redeem immediately
        // for the result.
        RWBoolean result = agent.dataClose();
    }
    catch (const RWxmsg& m) {
        cout << "Error : " << m.why() << endl;
    }
}

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. Note that an application is free to include the information at the beginning of a mail message.

RWISmtpAgent();

Constructs a default invalid RWISmtpAgent object. Using the default object results in an exception being thrown. Use the assignment operator to initialize the default RWISmtpAgent.

RWISmtpAgent(const RWCString& smtpHost, const RWCString& 
             localHost="localhost");

Constructs an RWISmtpAgent object that is ready to use in a subsequent call to the send method. The smtpHost is the IP address or the Internet host where the SMTP server of the connection resides. The localHost argument is the name of the client host used to greet the SMTP server. Generally this is the name of the client host, which is the default.

RWIOUResult<RWBoolean>
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.

RWIOUResult<RWSocketPortal>
send(const RWCString& from, const RWCString& to,
     headerMode h=RWISmtpAgent::DEFAULT_HEADERS); 

Returns an RWIOUResult with a redeemable RWSocketPortal. The RWSocketPortal that is returned should be used to complete the data portion of the protocol transfer. The from argument is a string representing the RFC822-compliant email address of the sender. Likewise, 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 injected automatically into the data stream before the portal becomes available. Note that almost all SMTP servers inject the From header into the email, however. Inclusion of headers does not prevent the application from including other headers (for example, a subject header); it is simply an easy way to include the bare minimum customary header information.

Note that the message sent through the socket portal must be formatted 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. The global function rwAddPeriods() (see the Utility Functions section) may be used to help you format your message.

After a successful data transfer using the returned RWSocketPortal, a call to the dataClose method must be performed to complete the body of the mail message.

©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.