Would you like to make this site your homepage? It's fast and easy...
Yes, Please make this my home page!
/***************************************************************************
*
* File: Socket.h
* Created: Sat Dec 4 1999
* (C) 1999 by David M. <captjay@superlink.net>
*
***************************************************************************/
/***************************************************************************
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or *
* (at your option) any later version. *
* *
***************************************************************************/
#ifndef SOCKET_H
#define SOCKET_H
#include <qstring.h>
#include <qobject.h>
#include <qtimer.h>
/**
* @author David M.
* @short Encapsulates TCP socket I/O communication.
*
* Encapsulates basic TCP socket communication. It is the base class for
* the ClientSocket and ServerSocket classes. Socket does not provide
* methods to connect to an IP/port or to listen on a port for connections. These
* specific tasks are included in ClientSocket and ServerSocket.
* @see ClientSocket
* @see ServerSocket
*/
class Socket : public QObject
{
Q_OBJECT
public:
/**
* Default constructor.
*/
Socket();
/**
* Copy constructor. A Socket object created with this constructor has the same state as the object it was
* copied from. The new object also shares the FD of the object it was copied from.
*/
Socket(Socket&);
/**
* Initialize a socket object from a standard UNIX file descriptor.
* This use is depreciated, and can cause problems if, for instance,
* the file descriptor is not valid or open.
*/
Socket(const int fileDescriptor);
//Destructor
~Socket();
//Public functions
/**
* Terminates communication on an open socket connection. Calling closeSocket() drops
* the connection and empties the socket's data buffer. Any data waiting to be read
* when closeSocket() is called is lost.
*
* PRECONDITIONS: isConnected()
*
* POSTCONDITIONS: !isConnected()
*/
void closeSocket();
/**
* Determine wether the socket object is currently connected.
* @return true if the object is in a valid connected state, false otherwise.
*/
bool isConnected() const;
/**
* Get the current error code of a socket object.
* @return Possible values are:
*
* (0) NoError: The socket object has not encountered any errors so far.
*
* (-1) ReadError: An error occured while the object was receiving data.
*
* (-2) WriteError: An error occured while the object was sending data.
*
* (111) ConnRefused: A connection request was refused.
*
* If an error occured, then the socket was disconnected at that moment.
* Use this method if you want to know what caused of a disconnection.
*
*/
int error() const;
/**
* Get the UNIX file descriptor associated with the socket object. This is used mostly
* for copy purposes; the socket's internal file descriptor should NOT be used externaly!
* @return The file descriptor of the socket, or 0 if the socket is not connected.
*/
int fileDesc();
/**
* Write data contained in a string to an open socket. In case of a write error, this method
* returns false, error() is set to WriteError, and the socket is disconnected.
*
* PRECONDITIONS: isConnected()
* @returns true if the write operation succeeded, false if a write error occured.
* @param data The QString object containing the data to write.
*
*/
bool sendTo(const QString& data);
/**
* Write data contained in an old format string to an open socket. In case of a write error, this method
* returns false, error() is set to WriteError, and the socket is disconnected.
*
* PRECONDITIONS: isConnected()
* @returns true if the write operation succeeded, false if a write error occured.
* @param data A pointer to the buffer containing the data to write. The buffer must be null-terminated.
*/
bool sendTo(const char* data);
/**
* Write data contained in a string to an open socket. In case of a write error, this method
* returns false, error() is set to WriteError, and the socket is disconnected.
*
* This method differs from sendTo in the fact that it adds an end-of-line ('\n') character after the
* data.
*
* PRECONDITIONS: isConnected()
* @returns true if the write operation succeeded, false if a write error occured.
* @param data The QString object containing the data to write.
*
*/
bool sendLine(const QString& data);
/**
* Write data contained in an old format string to an open socket. In case of a write error, this method
* returns false, error() is set to WriteError, and the socket is disconnected.
*
* This method differs from sendTo in the fact that it adds an end-of-line ('\n') character after the
* data.
*
* PRECONDITIONS: isConnected()
* @returns true if the write operation succeeded, false if a write error occured.
* @param data A pointer to the buffer containing the data to write. The buffer must be null-terminated.
*/
bool sendLine(const char* data);
/**
* manually set the file descriptor for the socket object to use. This method is depreciated.
*/
void setFD(const int FD);
/**
* Set the socket to asynchronous (non blocking) mode. This will make methods like dataWaiting() and read()
* return immediately, instead of waiting for information to arrive.
*
* This method is platform-dependant, and currently only works on Linux.
*/
bool setNonBlocking();
/**
* Read data that is waiting on a socket object. Even if you use blocking sockets, dataWaiting() must be called
* to actually read the data from the socket. Here is how sockets should be used, no matter if they are blocking
* or not:
* <pre>
* if (mySocket->dataWaiting()) {
* QString dataRead = mySocket->read();
* cout << dataRead << endl;
* }
* </pre>
* @return true if there is data to be read on the socket, false otherwise.
*/
bool dataWaiting();
/**
* Get a string containing the data that is in the socket's buffer. This method should only be called after
* a successful dataWaiting() call.
*
* @return a QString object containing the data the socket has in its buffer.
*/
QString read();
/**
* Write data contained in a QString to an open socket. After using this operator, you should check if any errors
* occured. This operator calls sendLine(), meaning that every string sent using it will add a '\n' at the
* end of the sent data.
*
* PRECONDITIONS: isConnected()
* @param data A string containing the data to write.
*/
Socket& operator<< (const QString& data);
/**
* Write data contained in an old format string to an open socket. After using this operator, you should check if any errors
* occured. This operator calls sendLine(), meaning that every string sent using it will add a '\n' at the
* end of the sent data.
*
*
* PRECONDITIONS: isConnected()
* @param data A pointer to the buffer containing the data to write. The buffer must be null-terminated.
*/
Socket& operator<< (const char* data);
/**
* error() returns this value when no error occured during an operation.
*/
static const int NoError = 0;
/**
* error() returns this value when an error occured while the socket was reading data. A socket that had a
* read error is disconnected.
*/
static const int ReadError = -1;
/**
* error() returns this value when an error occured while the socket was writing data. A socket that had a
* write error is disconnected.
*/
static const int WriteError = -2;
/**
* error() returns this value when an attempted connection could not be established. This error
* is set by @ref ClientSocket 's connectTo() method.
*/
static const int ConnRefused = 111;
signals:
void onDataWaiting(Socket*);
void onDisconnect(Socket*);
protected slots:
virtual void check();
protected:
// Protected functions
QString buffer() const;
// Member variables
int m_fd;
bool m_open;
int m_error;
bool m_ready;
QString* m_buffer;
QTimer m_timer;
};
#endif
| Generated by: nightsky@centauri on Sat Jan 15 23:06:10 2000, using kdoc 2.0a30. |
