diff options
Diffstat (limited to 'mimelib/doc/smtp.html')
| -rw-r--r-- | mimelib/doc/smtp.html | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/mimelib/doc/smtp.html b/mimelib/doc/smtp.html new file mode 100644 index 0000000..d76ab7c --- /dev/null +++ b/mimelib/doc/smtp.html @@ -0,0 +1,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> |