DwSmtpClient Man Page

From b479c22c713be413b9135be8f1d4e108d33f17f6 Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Sun, 6 Oct 2013 10:33:05 -0700 Subject: lurker-2.3 mimelib-3.1.1 --- mimelib/doc/smtp.html | 294 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 mimelib/doc/smtp.html (limited to 'mimelib/doc/smtp.html') 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 @@ + + + DwSmtpClient Man Page + + +

+ NAME +

+DwSmtpClient -- Class for handling the client side of an SMTP session +

+ SYNOPSIS +

class DW_EXPORT DwSmtpClient : public DwProtocolClient {
+
+public:
+
+    enum {
+        kCmdNoCommand=0,
+        kCmdHelo,
+        kCmdMail,
+        kCmdRcpt,
+        kCmdData,
+        kCmdRset,
+        kCmdSend,
+        kCmdSoml,
+        kCmdSaml,
+        kCmdVrfy,
+        kCmdExpn,
+        kCmdHelp,
+        kCmdNoop,
+        kCmdQuit,
+        kCmdTurn
+    };
+
+    DwSmtpClient();
+    virtual ~DwSmtpClient();
+    virtual int Open(const char* aServer, DwUint16 aPort=25);
+    int ReplyCode() const;
+    const DwString& Response() const;
+    int Helo();
+    int Mail(const char* aFrom);
+    int Rcpt(const char* aTo);
+    int Data();
+    int Rset();
+    int Send(const char* aFrom);
+    int Soml(const char* aFrom);
+    int Saml(const char* aFrom);
+    int Vrfy(const char* aName);
+    int Expn(const char* aName);
+    int Help(const char* aArg=0);
+    int Noop();
+    int Quit();
+    int Turn();
+    int SendData(const DwString& aStr);
+    int SendData(const char* aBuf, int aBufLen);
+};
+

+ DESCRIPTION +

+DwSmtpClient is a class that handles the client side of an +SMTP session. Specifically, DwSmtpClient 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. +

+DwSmtpClient is derived from +DwProtocolClient. For information +about inherited member functions, especially member functions for detecting +failures or errors, see the man page for +DwProtocolClient. +

+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. DwSmtpClient provides facilities for you to send +commands to the server and receive responses from the server. +

+DwSmtpClient 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 DwProtocolClient::LastError() and checking for a +zero return value. +

+To open a connection to the server, call the member function +Open() with the name of the server as an argument. +Open() accepts an optional argument that specifies the TCP +port that the server listens to. The default port is the standard SMTP port +(25). Open() may fail, so you should check the return value +to verify that it succeeded. To close the connection, call the inherited +member function DwProtocolClient::Close(). To check if a +connection is open, call the inherited member function +DwProtocolClient::IsOpen(). IsOpen() returns +a boolean value that indicates whether or not a call to +Open() was successful; it will not detect failure in the +network or a close operation by the remote host. +

+For each SMTP command, DwSmtpClient 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 DwProtocolClient::LastError() or +DwProtocolClient::LastFailure(). +

+After each command is sent, DwSmtpClient receives the server's +response and remembers it. The member function +ReplyCode() returns the numberic value of the reply code +received in response to the last command. Response() returns +the entire response from the server, including the reply code. If no response +is received, possibly because of a communications error or failure, +ReplyCode() returns zero and Response() returns +an empty string. +

+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, +DwSmtpClient provides the member function +SendData(). In the current implementation, +SendData() 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 +DwToCrLfEol() to do the conversion.) +SendData() 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 +SendData(); however, if you do so, please note the following +paragraph. +

+Note: Because of a feature (some might say bug) in the current implementation, +SendData() will not detect a '.' at the beginning of a line +if the CR LF '.' sequence is split between two calls to +SendData(). This problem will probably be resolved in a future +version, but be aware that such a change will require a change in +DwSmtpClient's interface. +

+ Public Member Functions +

+ DwSmtpClient() +

+Initializes the DwSmtpClient object. It is possible for the +constructor to fail. To verify that the constructor succeeded, call the member +function LastError() and check that it returns zero. (In +the Win32 implementation, the constructor calls the Winsock function +WSAStartup(), which may fail.) +

+ virtual int Open(const char* aServer, +DwUint16 aPort=25) +

+Opens a TCP connection to the server aServer at port +aPort. aServer 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 aPort is 25, the well-known +port for SMTP assigned by the Internet Assigned Numbers Authority (IANA). +

+If the connection attempt succeeds, the server sends a response. +Open() returns the server's numeric reply code. The full +response from the server can be retrieved by calling +Response(). +

+If the connection attempt fails, Open() returns 0. To determine +what error occurred when a connection attempt fails, call the inherited member +function DwProtocolClient::LastError(). To determine if a +failure also occurred, call the inherited member function +DwProtocolClient::LastFailure(). +

+ int ReplyCode() const + +

+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, ReplyCode() +returns zero. +

+ const DwString& Response() +const +

+Returns the entire response last received from the server. If no response +was received, perhaps because of a communications failure, +Response() returns an empty string. +

+ int Helo() +

+Sends the SMTP HELO command and returns the reply code received from the +server. If no response is received the function returns zero. +

+ int Mail(const char* aFrom) + +

+Sends the SMTP MAIL command with aFrom as the sender and +returns the reply code received from the server. If no response is received, +the function returns zero. +

+ int Rcpt(const char* aTo) + +

+Sends the SMTP RCPT command with aTo as the recipient and +returns the reply code received from the server. If no response is received, +the function returns zero. +

+ int Data() +

+Sends the SMTP DATA command and returns the reply code received from the +server. If no response is received, the function returns zero. +

+ int Rset() +

+Sends the SMTP RSET command and returns the reply code received from the +server. If no response is received, the function returns zero. +

+ int Send(const char* aFrom) + +

+Sends the SMTP SEND command with aFrom as the sender and +returns the reply code received from the server. If no response is received, +the function returns zero. +

+ int Soml(const char* aFrom) + +

+Sends the SMTP SOML command with aFrom as the sender and +returns the reply code received from the server. If no response is received, +the function returns zero. +

+ int Saml(const char* aFrom) + +

+Sends the SMTP SAML command with aFrom as the sender and +returns the reply code received from the server. If no response is received, +the function returns zero. +

+ int Vrfy(const char* aName) + +

+Sends the SMTP VRFY command with aName as the argument and +returns the reply code received from the server. If no response is received, +the function returns zero. +

+ int Expn(const char* aName) + +

+Sends the SMTP EXPN command with aName as the argument and +returns the reply code received from the server. If no response is received, +the function returns zero. +

+ int Help(const char* aArg=0) + +

+Sends the SMTP HELP command with aArg as the argument and +returns the reply code received from the server. If no response is received, +the function returns zero. +

+ int Noop() +

+Sends the SMTP NOOP command and returns the reply code received from the +server. If no response is received, the function returns zero. +

+ int Quit() +

+Sends the SMTP QUIT command and returns the reply code received from the +server. If no response is received, the function returns zero. +

+ int Turn() +

+Sends the SMTP TURN command and returns the reply code received from the +server. If no response is received, the function returns zero. +

+ int SendData(const DwString& +aStr)
+int SendData(const char* aBuf, int aBufLen) +

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

+In the current implementation, SendData() 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 +DwToCrLfEol() to do the conversion.) +SendData() 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 +SendData(); however, this may cause problems in the current +implementation if a CR LF '.' sequence is split between calls. + -- cgit v1.2.3