1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<HTML>
<HEAD>
<TITLE> DwSmtpClient Man Page </TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>
<FONT COLOR="navy"> NAME </FONT>
</H2>
<P>
DwSmtpClient -- Class for handling the client side of an SMTP session
<H2>
<FONT COLOR="navy"> SYNOPSIS </FONT>
</H2>
<PRE>class DW_EXPORT DwSmtpClient : public <A HREF="protocol.html">DwProtocolClient</A> {
public:
enum {
kCmdNoCommand=0,
kCmdHelo,
kCmdMail,
kCmdRcpt,
kCmdData,
kCmdRset,
kCmdSend,
kCmdSoml,
kCmdSaml,
kCmdVrfy,
kCmdExpn,
kCmdHelp,
kCmdNoop,
kCmdQuit,
kCmdTurn
};
<A HREF="smtp.html#DwSmtpClient">DwSmtpClient</A>();
virtual ~DwSmtpClient();
virtual int <A HREF="smtp.html#Open">Open</A>(const char* aServer, DwUint16 aPort=25);
int <A HREF="smtp.html#ReplyCode">ReplyCode</A>() const;
const DwString& <A HREF="smtp.html#Response">Response</A>() const;
int <A HREF="smtp.html#Helo">Helo</A>();
int <A HREF="smtp.html#Mail">Mail</A>(const char* aFrom);
int <A HREF="smtp.html#Rcpt">Rcpt</A>(const char* aTo);
int <A HREF="smtp.html#Data">Data</A>();
int <A HREF="smtp.html#Rset">Rset</A>();
int <A HREF="smtp.html#Send">Send</A>(const char* aFrom);
int <A HREF="smtp.html#Soml">Soml</A>(const char* aFrom);
int <A HREF="smtp.html#Saml">Saml</A>(const char* aFrom);
int <A HREF="smtp.html#Vrfy">Vrfy</A>(const char* aName);
int <A HREF="smtp.html#Expn">Expn</A>(const char* aName);
int <A HREF="smtp.html#Help">Help</A>(const char* aArg=0);
int <A HREF="smtp.html#Noop">Noop</A>();
int <A HREF="smtp.html#Quit">Quit</A>();
int <A HREF="smtp.html#Turn">Turn</A>();
int <A HREF="smtp.html#SendData">SendData</A>(const DwString& aStr);
int <A HREF="smtp.html#SendData">SendData</A>(const char* aBuf, int aBufLen);
};
</PRE>
<H2>
<FONT COLOR="navy"> DESCRIPTION </FONT>
</H2>
<P>
<B><TT>DwSmtpClient</TT></B> is a class that handles the client side of an
SMTP session. Specifically, <B><TT>DwSmtpClient</TT></B> provides facilities
for opening a connection to an SMTP server, sending commands and data to
the server, receiving responses from the server, and closing the connection.
The protocol implemented is the Simple Mail Transport Protocol, as specified
in RFC-821.
<P>
<B><TT>DwSmtpClient</TT></B> is derived from
<B><TT><A HREF="protocol.html">DwProtocolClient</A></TT></B>. For information
about inherited member functions, especially member functions for detecting
failures or errors, see the man page for
<B><TT>DwProtocolClient</TT></B>.
<P>
In an SMTP session, the client sends commands to the server and receives
responses from the server. A client command consists of a command word and
possibly an argument. A server response consists of a three-digit numeric
reply code followed by text. The reply code indicates a success or failure
condition. <B><TT>DwSmtpClient</TT></B> provides facilities for you to send
commands to the server and receive responses from the server.
<P>
<B><TT>DwSmtpClient</TT></B> has only a default constructor. On Win32 platforms,
it is possible for the constructor to fail. (It calls WSAStartup().) You
should verify that the constructor succeeded by calling the inherited member
function <B><TT>DwProtocolClient::LastError()</TT></B> and checking for a
zero return value.
<P>
To open a connection to the server, call the member function
<B><TT>Open()</TT></B> with the name of the server as an argument.
<B><TT>Open()</TT></B> accepts an optional argument that specifies the TCP
port that the server listens to. The default port is the standard SMTP port
(25). <B><TT>Open()</TT></B> may fail, so you should check the return value
to verify that it succeeded. To close the connection, call the inherited
member function <B><TT>DwProtocolClient::Close()</TT></B>. To check if a
connection is open, call the inherited member function
<B><TT>DwProtocolClient::IsOpen()</TT></B>. <B><TT>IsOpen()</TT></B> returns
a boolean value that indicates whether or not a call to
<B><TT>Open()</TT></B> was successful; it will not detect failure in the
network or a close operation by the remote host.
<P>
For each SMTP command, <B><TT>DwSmtpClient</TT></B> has a member function
that sends that command and receives the server's response. If the command
takes an argument, then that argument is passed as a function argument to
the command function. The command functions return the numeric value of the
three-digit reply code returned by the server. Your program must check the
reply code to determine whether or not the command was accepted and performed
by the server. In some cases, because of a communications error or some other
error, it is not possible for the command function to send the command or
receive the response. When this happens, the command function will return
0. You can determine the precise error or failure by calling the inherited
member functions <B><TT>DwProtocolClient::LastError()</TT></B> or
<B><TT>DwProtocolClient::LastFailure()</TT></B>.
<P>
After each command is sent, <B><TT>DwSmtpClient</TT></B> receives the server's
response and remembers it. The member function
<B><TT>ReplyCode()</TT></B> returns the numberic value of the reply code
received in response to the last command. <B><TT>Response()</TT></B> returns
the entire response from the server, including the reply code. If no response
is received, possibly because of a communications error or failure,
<B><TT>ReplyCode()</TT></B> returns zero and <B><TT>Response()</TT></B> returns
an empty string.
<P>
Following a successful response to the DATA command, an SMTP client sends
multiple lines of text to the server. To perform this bulk data transfer,
<B><TT>DwSmtpClient</TT></B> provides the member function
<B><TT>SendData()</TT></B>. In the current implementation,
<B><TT>SendData()</TT></B> does not convert end of line characters, so it
is your responsibility to convert the end of line characters to CR LF, if
necessary. (You may use the utility function
<B><TT>DwToCrLfEol()</TT></B> to do the conversion.)
<B><TT>SendData()</TT></B> will perform the character stuffing to protect
'.' at the beginning of a line, and it will append the final [CR LF] '.'
CR LF. It is possible to divide data and make multiple calls to
<B><TT>SendData()</TT></B>; however, if you do so, please note the following
paragraph.
<P>
Note: Because of a feature (some might say bug) in the current implementation,
<B><TT>SendData()</TT></B> will not detect a '.' at the beginning of a line
if the CR LF '.' sequence is split between two calls to
<B><TT>SendData()</TT></B>. This problem will probably be resolved in a future
version, but be aware that such a change will require a change in
<B><TT>DwSmtpClient</TT></B>'s interface.
<H2>
<FONT COLOR="navy"> Public Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> <A NAME="DwSmtpClient">DwSmtpClient</A>() </B></FONT>
<P>
Initializes the <B><TT>DwSmtpClient</TT></B> object. It is possible for the
constructor to fail. To verify that the constructor succeeded, call the member
function <B><TT>LastError()</TT></B> and check that it returns zero. (In
the Win32 implementation, the constructor calls the Winsock function
<B><TT>WSAStartup()</TT></B>, which may fail.)
<P>
<FONT COLOR="teal"><B> virtual int <A NAME="Open">Open</A>(const char* aServer,
DwUint16 aPort=25) </B></FONT>
<P>
Opens a TCP connection to the server <B><TT>aServer</TT></B> at port
<B><TT>aPort</TT></B>. <B><TT>aServer</TT></B> may be either a host name,
such as "smtp.acme.com" or an IP number in dotted decimal format, such as
"147.81.64.60". The default value for <B><TT>aPort</TT></B> is 25, the well-known
port for SMTP assigned by the Internet Assigned Numbers Authority (IANA).
<P>
If the connection attempt succeeds, the server sends a response.
<B><TT>Open()</TT></B> returns the server's numeric reply code. The full
response from the server can be retrieved by calling
<B><TT>Response()</TT></B>.
<P>
If the connection attempt fails, <B><TT>Open()</TT></B> returns 0. To determine
what error occurred when a connection attempt fails, call the inherited member
function <B><TT>DwProtocolClient::LastError()</TT></B>. To determine if a
failure also occurred, call the inherited member function
<B><TT>DwProtocolClient::LastFailure()</TT></B>.
<P>
<FONT COLOR="teal"><B> int <A NAME="ReplyCode">ReplyCode</A>() const
</B></FONT>
<P>
Returns the numeric value of the three-digit reply code received from the
server in response to the last client command. If no response was received,
perhaps because of a communications failure, <B><TT>ReplyCode()</TT></B>
returns zero.
<P>
<FONT COLOR="teal"><B> const DwString& <A NAME="Response">Response</A>()
const </B></FONT>
<P>
Returns the entire response last received from the server. If no response
was received, perhaps because of a communications failure,
<B><TT>Response()</TT></B> returns an empty string.
<P>
<FONT COLOR="teal"><B> int <A NAME="Helo">Helo</A>() </B></FONT>
<P>
Sends the SMTP HELO command and returns the reply code received from the
server. If no response is received the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Mail">Mail</A>(const char* aFrom)
</B></FONT>
<P>
Sends the SMTP MAIL command with <B><TT>aFrom</TT></B> as the sender and
returns the reply code received from the server. If no response is received,
the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Rcpt">Rcpt</A>(const char* aTo)
</B></FONT>
<P>
Sends the SMTP RCPT command with <B><TT>aTo</TT></B> as the recipient and
returns the reply code received from the server. If no response is received,
the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Data">Data</A>() </B></FONT>
<P>
Sends the SMTP DATA command and returns the reply code received from the
server. If no response is received, the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Rset">Rset</A>() </B></FONT>
<P>
Sends the SMTP RSET command and returns the reply code received from the
server. If no response is received, the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Send">Send</A>(const char* aFrom)
</B></FONT>
<P>
Sends the SMTP SEND command with <B><TT>aFrom</TT></B> as the sender and
returns the reply code received from the server. If no response is received,
the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Soml">Soml</A>(const char* aFrom)
</B></FONT>
<P>
Sends the SMTP SOML command with <B><TT>aFrom</TT></B> as the sender and
returns the reply code received from the server. If no response is received,
the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Saml">Saml</A>(const char* aFrom)
</B></FONT>
<P>
Sends the SMTP SAML command with <B><TT>aFrom</TT></B> as the sender and
returns the reply code received from the server. If no response is received,
the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Vrfy">Vrfy</A>(const char* aName)
</B></FONT>
<P>
Sends the SMTP VRFY command with <B><TT>aName</TT></B> as the argument and
returns the reply code received from the server. If no response is received,
the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Expn">Expn</A>(const char* aName)
</B></FONT>
<P>
Sends the SMTP EXPN command with <B><TT>aName</TT></B> as the argument and
returns the reply code received from the server. If no response is received,
the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Help">Help</A>(const char* aArg=0)
</B></FONT>
<P>
Sends the SMTP HELP command with <B><TT>aArg</TT></B> as the argument and
returns the reply code received from the server. If no response is received,
the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Noop">Noop</A>() </B></FONT>
<P>
Sends the SMTP NOOP command and returns the reply code received from the
server. If no response is received, the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Quit">Quit</A>() </B></FONT>
<P>
Sends the SMTP QUIT command and returns the reply code received from the
server. If no response is received, the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="Turn">Turn</A>() </B></FONT>
<P>
Sends the SMTP TURN command and returns the reply code received from the
server. If no response is received, the function returns zero.
<P>
<FONT COLOR="teal"><B> int <A NAME="SendData">SendData</A>(const DwString&
aStr) <BR>
int SendData(const char* aBuf, int aBufLen) </B></FONT>
<P>
Sends bulk data to the server and returns the reply code received. A bulk
data transfer follows a DATA command and is used to send a complete message
to the server.
<P>
In the current implementation, <B><TT>SendData()</TT></B> does not convert
end of line characters, so it is your responsibility to convert the end of
line characters to CR LF, if necessary. (You may use the utility function
<B><TT>DwToCrLfEol()</TT></B> to do the conversion.)
<B><TT>SendData()</TT></B> will perform the character stuffing to protect
'.' at the beginning of a line, and it will append the final [CR LF] '.'
CR LF. It is possible to divide the data and make multiple calls to
<B><TT>SendData()</TT></B>; however, this may cause problems in the current
implementation if a CR LF '.' sequence is split between calls.
</BODY></HTML>
|
