Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
author: toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> 2009-11-25 17:56:58 +0000
committer: toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> 2009-11-25 17:56:58 +0000
commit: 460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 (patch)
tree: 67208f7c145782a7e90b123b982ca78d88cc2c87 /mimelib/doc/protocol.html
download: tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.tar.gz
tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.zip
1 files changed, 274 insertions, 0 deletions
diff --git a/mimelib/doc/protocol.html b/mimelib/doc/protocol.html
new file mode 100644
index 000000000..28bb81db6
--- /dev/null
+++ b/mimelib/doc/protocol.html
@@ -0,0 +1,274 @@
+<HTML>
+<HEAD>
+  <TITLE> DwProtocolClient Man Page </TITLE>
+</HEAD>
+<BODY BGCOLOR="#FFFFFF">
+<H2>
+  <FONT COLOR="navy"> NAME </FONT>
+</H2>
+<P>
+DwProtocolClient -- Base class for all protocol clients
+<H2>
+  <FONT COLOR="navy"> SYNOPSIS </FONT>
+</H2>
+<PRE>class DW_EXPORT DwProtocolClient {
+
+public:
+
+    enum Failure {
+        kFailNoFailure      = 0, // No failure
+        kFailNoWinsock      = 1, // A usable Winsock DLL could not be found
+        kFailNetDown        = 2, // The network is down
+        kFailHostNotFound   = 3, // The server was not found
+        kFailConnReset      = 4, // The connection was reset
+        kFailNetUnreachable = 5, // The network is unreachable
+        kFailTimedOut       = 6, // Timed out while waiting for an operation
+                                 // to complete
+        kFailConnDropped    = 7,
+        kFailConnRefused    = 8,
+        kFailNoResources    = 9
+    };
+
+    enum Error {
+        kErrNoError = 0,
+        kErrUnknownError = 0x4000,
+        kErrBadParameter = 0x4001,
+        kErrBadUsage     = 0x4002,
+        kErrNoWinsock    = 0x4003,  // Win32
+        kErrHostNotFound = 0x5000,  // UNIX
+        kErrTryAgain     = 0x5001,  // UNIX
+        kErrNoRecovery   = 0x5002,  // UNIX
+        kErrNoData       = 0x5003,  // UNIX
+        kErrNoAddress    = 0x5004,  // UNIX
+    };
+
+protected:
+
+    <A HREF="protocol.html#DwProtocolClient">DwProtocolClient</A>();
+
+public:
+
+    virtual <A HREF="protocol.html#~DwProtocolClient">~DwProtocolClient</A>();
+    virtual int <A HREF="protocol.html#Open">Open</A>(const char* aServer, DwUint16 aPort);
+    DwBool <A HREF="protocol.html#IsOpen">IsOpen</A>() const;
+    int <A HREF="protocol.html#Close">Close</A>();
+    int <A HREF="protocol.html#SetReceiveTimeout">SetReceiveTimeout</A>(int aSecs);
+    int <A HREF="protocol.html#LastCommand">LastCommand</A>() const;
+    int <A HREF="protocol.html#LastFailure">LastFailure</A>() const;
+    const char* <A HREF="protocol.html#LastFailureStr">LastFailureStr</A>() const;
+    int <A HREF="protocol.html#LastError">LastError</A>() const;
+    const char* <A HREF="protocol.html#LastErrorStr">LastErrorStr</A>() const;
+
+protected:
+
+    enum {
+        kWSAStartup=1,  // Win32
+        kgethostbyname,
+        ksocket,
+        ksetsockopt,
+        kconnect,
+        ksend,
+        krecv,
+        kclose,         // UNIX
+        kclosesocket,   // Win32
+        kselect
+    };
+    DwBool      mIsDllOpen;
+    DwBool      mIsOpen;
+    SOCKET      mSocket;
+    DwUint16    mPort;
+    char*       mServerName;
+    int         mReceiveTimeout;
+    int         mLastCommand;
+    int         mFailureCode;
+    const char* mFailureStr;
+    int         mErrorCode;
+    const char* mErrorStr;
+    virtual void <A HREF="protocol.html#HandleError">HandleError</A>(int aErrorCode, int aSystemCall);
+    int <A HREF="protocol.html#PSend">PSend</A>(const char* aBuf, int aBufLen);
+    int <A HREF="protocol.html#PReceive">PReceive</A>(char* aBuf, int aBufSize);
+};
+</PRE>
+<H2>
+  <FONT COLOR="navy"> DESCRIPTION </FONT>
+</H2>
+<P>
+<B><TT>DwProtocolClient</TT></B> is the base class for other classes that
+implement specific protocols, such as SMTP, POP, and NNTP.
+<B><TT>DwProtocolClient</TT></B> serves two purposes. First, It combines
+operations common to all its derived classes, such as opening a TCP connection
+to the server. Second, it provides a platform-independent interface to the
+network services required by its subclasses.
+<P>
+There are two separate implementations of
+<B><TT>DwProtocolClient</TT></B>: one for Berkeley sockets under UNIX, and
+one for Winsock under Win32. The interface is the same for both implementations,
+thus providing platform independence.
+<P>
+There are two platform-specific details that you should be aware of. First,
+if you are writing a UNIX program, you should be sure to handle the SIGPIPE
+signal. This signal is raised when a program tries to write to a TCP connection
+that was shutdown by the remote host. The default action for this signal
+is to terminate the program. To prevent this from happening in your program,
+you should either catch the signal or tell the operating system to ignore
+it. Second, if you are writing a Win32 application for Windows NT or Windows95,
+you should be aware of the fact that the constructor calls the Winsock function
+<B><TT>WSAStartup()</TT></B> to initialize the Winsock DLL. (The destructor
+calls <B><TT>WSACleanup()</TT></B>.) Because it is possible for
+<B><TT>WSAStartup()</TT></B> to fail, it is also possible that the constructor
+may fail. To verify that the constructor has succeeded, call the member function
+<B><TT>LastError()</TT></B> and check that it returns zero.
+<P>
+To open a connection to a server, call <B><TT>Open()</TT></B> with the server
+name and TCP port number as arguments. <B><TT>Open()</TT></B> is declared
+virtual; derived classes may override this member function.
+<B><TT>Open()</TT></B> may fail, so you should check the return value to
+verify that it succeeded. To close the connection, call
+<B><TT>Close()</TT></B>. To check if a connection is open, call
+<B><TT>IsOpen()</TT></B>. <B><TT>IsOpen()</TT></B> returns a 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>
+<B><TT>DwProtocolClient</TT></B> sets a timeout on receive operations on
+the TCP connection. The default value of the timeout period is 90 seconds.
+To change the default value, call <B><TT>SetReceiveTimeout()</TT></B> and
+pass the new value as an argument.
+<P>
+Whenever <B><TT>DwProtocolClient</TT></B> cannot complete an operation, it
+is because an error has occurred. Most member functions indicate that an
+error has occurred via their return values. For most member functions, a
+return value of -1 indicates an error. To get the specific error that has
+occurred, call <B><TT>LastError()</TT></B>, which returns either the system
+error code or a MIME++ defined error code. To get a text string that describes
+the error, call <B><TT>LastErrorStr()</TT></B>.
+<P>
+Some errors are also considered "failures." A failure occurs when an operation
+cannot be completed because of conditions external to the program. For example,
+a failure occurs when the network is down or when an application's user enters
+bad input. Errors that occur because of programmer error are not considered
+failures. If an error occurs, you should call <B><TT>LastError()</TT></B>
+to determine the error, but you should also call
+<B><TT>LastFailure()</TT></B> to determine if a failure occurred. In interactive
+applications, failures should always be reported to the application's user.
+To get a text string that describes a failure, call
+<B><TT>LastFailureStr()</TT></B>.
+<P>
+It is possible to translate the error and failure message strings to a language
+other than English. To do this, you may override the virtual function
+<B><TT>HandleError()</TT></B>.
+<H2>
+  <FONT COLOR="navy"> Public Member Functions </FONT>
+</H2>
+<P>
+<FONT COLOR="teal"><B> virtual
+<A NAME="~DwProtocolClient">~DwProtocolClient</A>() </B></FONT>
+<P>
+Frees the resources used by this object. In a Win32 environment, the destructor
+calls <B><TT>WSACleanup()</TT></B>.
+<P>
+<FONT COLOR="teal"><B> virtual int <A NAME="Open">Open</A>(const char* aServer,
+DwUint16 aPort) </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.59". If the connection attempt succeeds,
+<B><TT>Open()</TT></B> returns 0; othewise, it returns -1. To determine what
+error occurred when the connection attempt fails, call the member function
+<B><TT>LastError()</TT></B>. To determine if a failure also occurred, call
+the member function <B><TT>LastFailure()</TT></B>.
+<P>
+<FONT COLOR="teal"><B> DwBool <A NAME="IsOpen">IsOpen</A>() const </B></FONT>
+<P>
+Returns true value if a connection to the server is open.
+<B><TT>IsOpen()</TT></B> will return a true value if 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>
+<FONT COLOR="teal"><B> int <A NAME="Close">Close</A>() </B></FONT>
+<P>
+Closes the connection to the server. Returns 0 if successful, or returns
+-1 if unsuccessful.
+<P>
+<FONT COLOR="teal"><B> int
+<A NAME="SetReceiveTimeout">SetReceiveTimeout</A>(int aSecs) </B></FONT>
+<P>
+Changes the default timeout for receive operations on the socket to
+<B><TT>aSecs</TT></B> seconds. The default value is 90 seconds.
+<P>
+<FONT COLOR="teal"><B> int <A NAME="LastCommand">LastCommand</A>() const
+</B></FONT>
+<P>
+Returns an enumerated value indicating the last command sent to the server.
+Enumerated values are defined in subclasses of
+<B><TT>DwProtocolClient</TT></B>.
+<P>
+<FONT COLOR="teal"><B> int <A NAME="LastFailure">LastFailure</A>() const
+</B></FONT>
+<P>
+Returns an enumerated value indicating what failure last occurred.
+<P>
+<FONT COLOR="teal"><B> const char*
+<A NAME="LastFailureStr">LastFailureStr</A>() const </B></FONT>
+<P>
+Returns a failure message string associated with the failure code returned
+by <B><TT>LastFailure()</TT></B>.
+<P>
+<FONT COLOR="teal"><B> int <A NAME="LastError">LastError</A>() const
+</B></FONT>
+<P>
+Returns an error code for the last error that occurred. Normally, the error
+code returned is an error code returned by a system call;
+<B><TT>DwProtocolClient</TT></B> does no translation of error codes returned
+by system calls. In some cases, an error code defined by MIME++ may returned
+to indicate improper use of the <B><TT>DwProtocolClient</TT></B> class.
+<P>
+<FONT COLOR="teal"><B> const char* <A NAME="LastErrorStr">LastErrorStr</A>()
+const </B></FONT>
+<P>
+Returns an error message string associated with the error code returned by
+<B><TT>LastError()</TT></B>.
+<H2>
+  <FONT COLOR="navy"> Protected Member Functions </FONT>
+</H2>
+<P>
+<B><FONT COLOR="teal"> <A NAME="DwProtocolClient">DwProtocolClient</A>()
+</FONT></B>
+<P>
+Initializes the <B><TT>DwProtocolClient</TT></B> object. In a Win32 environment,
+this constructor calls <B><TT>WSAStartup()</TT></B> to initialize the Winsock
+DLL. To verify that the DLL was initialized successfully, call the member
+function <B><TT>LastError()</TT></B> and verify that it returns zero.
+<P>
+<B><FONT COLOR="teal"> virtual void <A NAME="HandleError">HandleError</A>(int
+aErrorCode, int aSystemCall) </FONT></B>
+<P>
+Interprets error codes. <B><TT>aErrorCode</TT></B> is an error code, which
+may be a system error code, or an error code defined by
+<B><TT>DwProtocolClient</TT></B>. <B><TT>aSystemCall</TT></B> is an enumerated
+value defined by <B><TT>DwProtocolClient</TT></B> that indicates the last
+system call made, which should be the system call that set the error code.
+<B><TT>HandleError()</TT></B> sets values for <B><TT>mErrorStr</TT></B>,
+<B><TT>mFailureCode</TT></B>, and <B><TT>mFailureStr</TT></B>.
+<P>
+<B><FONT COLOR="teal"> int <A NAME="PSend">PSend</A>(const char* aBuf, int
+aBufLen) </FONT></B>
+<P>
+Sends <B><TT>aBufLen</TT></B> characters from the buffer
+<B><TT>aBuf</TT></B>. Returns the number of characters sent. If the number
+of characters sent is less than the number of characters specified in
+<B><TT>aBufLen</TT></B>, the caller should call
+<B><TT>LastError()</TT></B> to determine what, if any, error occurred. To
+determine if a failure also occurred, call the member function
+<B><TT>LastFailure()</TT></B>.
+<P>
+<B><FONT COLOR="teal"> int <A NAME="PReceive">PReceive</A>(char* aBuf, int
+aBufSize) </FONT></B>
+<P>
+Receives up to <B><TT>aBufSize</TT></B> characters into the buffer
+<B><TT>aBuf</TT></B>. Returns the number of characters received. If zero
+is returned, the caller should call the member function
+<B><TT>LastError()</TT></B> to determine what, if any, error occurred. To
+determine if a failure also occurred, call the member function
+<B><TT>LastFailure()</TT></B>.
+</BODY></HTML>
author	toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>	2009-11-25 17:56:58 +0000
committer	toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>	2009-11-25 17:56:58 +0000
commit	460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 (patch)
tree	67208f7c145782a7e90b123b982ca78d88cc2c87 /mimelib/doc/protocol.html
download	tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.tar.gz tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.zip