<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,
tdesocket,
ksetsockopt,
kconnect,
ksend,
krecv,
kclose, // UNIX
kclosesocket, // Win32
tdeselect
};
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>