From f7a9549bd6ad83f2e0bceec9cddacfa5e3f84a54 Mon Sep 17 00:00:00 2001 From: Mike Buland Date: Mon, 1 May 2006 17:11:04 +0000 Subject: libbu++ is finally laid out the way it should be, trunk, branches, and tags. --- src/connection.h | 387 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 387 insertions(+) create mode 100644 src/connection.h (limited to 'src/connection.h') diff --git a/src/connection.h b/src/connection.h new file mode 100644 index 0000000..efb8630 --- /dev/null +++ b/src/connection.h @@ -0,0 +1,387 @@ +/**\file + * Contains the Connection class. + *@author Mike Buland + */ + +#ifndef CONNECTION_H +#define CONNECTION_H + +#include "multilog.h" +#include "flexbuf.h" +#include "protocol.h" + +/** Represents a single connection on a network. While these connections + * may be treated more or less just like files, occasionally problems arise + * when writing data at any time you feel like. Therefore you run all your + * data through a Connection, which buffers all data and makes sure no + * buffers are exceeded and nothing inappropriate for the recipient of the + * data is sent. + *@author Mike Buland + */ +class Connection +{ +public: + /** + * Construct a blank and non-connected Connection. The created object is + * not yet connected to anything, and most of the functions except open are + * unusable. + */ + Connection(); + + /** + * Destroy the connection, clean up all pending data requests and close the + * contained socket. This does not send out pending data, especially since + * such an operation could take considerable time, depending on the pending + * data and state of the receiving end. + */ + ~Connection(); + + /** + * Open a connection to a remote server. This sets up this connection as + * a client instead of a server and does all of the work that needs to be + * done to actually open an INET_AF connection, which is a lot of work. + *@param sAddr The address to connect to. This can be in any format + * normally understood by your system to be an address, ip, domain name, + * etc. + *@param nPort The port number to connect to on the remote server. + *@returns True if the connection was successful and everything is setup, + * false if there were any of a dozen errors and the connection is not set. + *@todo Make this function add log entries to a standard MultiLog if + * something goes wrong. + */ + bool open( const char *sAddr, int nPort ); + + /** Append the given data to the output. The data is presumed to be null + * terminated. To put binary data into the stream, use the other + * appendOutput function. This should be the only method used to + * communicate with the socket. + *@param lpOutput The data to add to the output queue. + *@param nSize How much data is in the lpOutput buffer. If this value + * is -1 then the program treats lpOutput as a null-terminated string. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const char *lpOutput, int nSize=-1 ); + + /** + * Append the character to the output. + *@param lOutput The character to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const char lOutput ); + + /** + * Append the short to the output. + *@param lOutput The short to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const short lOutput ); + + /** + * Append the int to the output. + *@param lOutput The int to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const int lOutput ); + + /** + * Append the long to the output. + *@param lOutput The long to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const long lOutput ); + + /** + * Append the float to the output. + *@param lOutput The float to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const float lOutput ); + + /** + * Append the double to the output. + *@param lOutput The double to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const double lOutput ); + + /** + * Append the unsigned char to the output. + *@param lOutput The unsigned char to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const unsigned char lOutput ); + + /** + * Append the unsigned short to the output. + *@param lOutput The unsigned short to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const unsigned short lOutput ); + + /** + * Append the unsigned int to the output. + *@param lOutput The unsigned int to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const unsigned int lOutput ); + + /** + * Append the unsigned long to the output. + *@param lOutput The unsigned long to add to the output queue. + *@returns True if everything is ok, false otherwise. + */ + bool appendOutput( const unsigned long lOutput ); + + /** + * Writes all input data in the buffer in a dual-view ascii and hex display + * to a file. There are a number of options that also help with debugging. + *@param lpPrefix Text to be added to the begining of every line written + * out. The default is a blank string. + *@param fh The file to write the data to in text mode. This is stdout by + * default, but could be any already open file handle. + *@param nBytesMax The maximum number of bytes to write to the output. The + * amount of data can be overwhelming sometimes, so you can limit it. The + * default value is -1, which is also unlimited. + */ + void printInputDebug( const char *lpPrefix="", FILE *fh=stdout, int nBytesMax=-1 ); + + /** + * Writes all output data in the buffer in a dual-view ascii and hex display + * to a file. There are a number of options that also help with debugging. + *@param lpPrefix Text to be added to the begining of every line written + * out. The default is a blank string. + *@param fh The file to write the data to in text mode. This is stdout by + * default, but could be any already open file handle. + *@param nBytesMax The maximum number of bytes to write to the output. The + * amount of data can be overwhelming sometimes, so you can limit it. The + * default value is -1, which is also unlimited. + */ + void printOutputDebug( const char *lpPrefix="", FILE *fh=stdout, int nBytesMax=-1 ); + + /** + * This is the low-level generic function that is called by both + * printInputDebug and printOutputDebug. It works effectively just like + * both of them, except that you can give it a raw pointer to the data to + * print out. This probably doesn't belong in this class, but this was + * where I was when I needed it. + *@param pData A pointer to the data to write. This is not treated as a + * null terminated string, so make sure that the nDataLen param is set + * properly. + *@param nDataLen The number of bytes that are in pData and that you want to + * see. + *@param lpName The name of the data, this is used in the header where it + * says "Displaying nnn bytes of ." A good example would be input + * or output. + *@param lpPrefix Text to put before every line output. This just makes it + * easier to tell large blocks apart in the output. + *@param fh The file handle to write all data to. + *@param nBytesMax The maximum number of bytes. This parameter is stupid. + * If it is set to -1, then nDataLen is used, otherwise the smaller value is + * used as the number of bytes to output. + *@todo Put this function somewhere more deserving. + *@todo Remove the nBytesMax param, we need that in the other functions, + * not this one! + */ + void printDataDebug( const unsigned char *pData, long nDataLen, const char *lpName, const char *lpPrefix, FILE *fh, int nBytesMax ); + + /** Append the given data to the input. The data is presumed to be null + * terminated. To put binary data into the stream, use the other + * appendInput function. This is mainly used by internal routines. + *@param lpInput The data to add to the input queue. + *@param nSize How much data is in the lpInput buffer. If this value + * is -1 then the program treats lpOutput as a null-terminated string. + *@returns True if everything is ok, false otherwise. + */ + bool appendInput( const char *lpInput, int nSize=-1 ); + + /** Searches through the current pending input for a certain character. + * This is useful for finding out where exactly the end of a line is, for + * example, to see if a command has been entered yet. + *@param cTarget The character to search for. + *@returns The position of the target relative to the begining of the input + * or -1 if the target wasn't found. + */ + int scanInputFor( char cTarget ); + + /** Gets a pointer to the output buffer. This is mainly used by internal + * routines, and is cleared every click when data is sent out again. + *@returns A pointer to the buffer holding the pending output data. + */ + const char *getOutput(); + + /** Gets a pointer to the start of the input buffer's active data + * section. Use this to gain access to the input you need to do + * your job. + *@returns A pointer to the data in the input buffer. Do not delete this. + */ + const char *getInput(); + + /** Clears all pending output, this is mainly just used internally. + *@returns True if operation was a success, otherwise false. + */ + bool clearOutput(); + + /** Clears all pending input, weather it's been used or not. Please + * refrain from calling this during normal operation, use usedInput + * instead, it's much safer. + *@returns True if the operation was a success, false otherwise. + */ + bool clearInput(); + + /** Sets the socket that should be used internally. + *@param nNewSocket The new socket to work with. + */ + void setSocket( int nNewSocket ); + + /** Gets the handle (number) of the working socket. This can be a + * dangerous function to call, please refrain from calling it directly + * if any alternative can be found. + *@returns The number of the working socket. + */ + int getSocket(); + + /** Determines if the connection is still active. + *@returns True if the connection is active, false otherwise. + */ + bool isActive(); + + /** Clears all buffers and sets up the connection to be reused. + * Does not actually close the socket, that's handled by the + * ConnectionManager + */ + void close(); + + /** Opens a socket. Really just sets up the connection for use since + * the socket itself was created and opened by the ConnectionManager. + * This also calls setSocket so you don't have to. + *@param nNewSocket The socket to assosiate with. + */ + bool open( int nNewSocket ); + + /** + * Reads all pending input from the connection. If this is called outside + * of the ConnectionManager it will usually block indefinately waiting for + * new data. The only way to change this behaviour is to modify the socket + * low-level when you connect it manually, or, preferably use the other + * readInput function to control blocking time. + *@returns True socket is still connected, otherwise false. + */ + bool readInput(); + + /** + * Reads all pending input from the connection, blocking up to nSec + * seconds and nUSec micro-seconds for the data. This uses select to + * simulate blocking, but has the same effect as standard io blocking. + * If you don't want to block, just set both values to zero. + *@param nSec Max seconds to wait. + *@param nUSec Max micro-seconds to wait. + */ + bool readInput( int nSec, int nUSec ); + + /** Writes all data that is pending to the socket. + *@returns True if all data was written succesfully, false otherwise. + */ + bool writeOutput(); + + /** Determines if the connection has output waiting to go out. + *@returns true if there is pending output, otherwise false. + */ + bool hasOutput(); + + /** Sets internal flags so that this connection will be deleted next + * time through the ConnectionManager. + */ + void disconnect(); + + /** Determines if this connection is ready to be disconnected or not. + *@returns True if it is time to disconnect, false if it isn't. + */ + bool needDisconnect(); + + /** Tells the caller if there is pending input waiting to be processed. + *@returns True if there is pending input that has not been used, returns + * false if there isn't. + */ + bool hasInput(); + + /** Removes bytes from the begining of the input queue. Use this after + * getting the input and processing as much as you need to. + *@param nAmount The number of bytes used. + *@returns true if the update was successful, otherwise false. + */ + bool usedInput( int nAmount ); + + /** Sets the protocol to be used by this connection. All data in and out + * passes through the protocol object, which may process that data to + * filter out and process any special messages that may have been + * included. Everything that isn't processed can be accessed in the + * standard method. + *@param pNewProtocol A pointer to a protocol object that you want to + * use. + */ + void setProtocol( class Protocol *pNewProtocol ); + + /** Gets the number of bytes that are waiting in the input queue, the data + * that has yet to be processed. + *@returns The number of bytes in the input queue. + */ + int getInputAmnt(); + + /** Gets the number of bytes that are waiting in the output queue, the data + * that has yet to be sent to the connected socket. + *@returns The number of bytes in the input queue. + */ + int getOutputAmnt(); + + /** Gets a pointer to the protocol that is attatched to this connection + * object. This is useful to set modes, and send special commands in + * addition to the standard raw data reads and writes that are normally + * permitted. In fact, in everything besides a raw telnet protocol all + * data should be sent through the protocol and not the connection object. + *@returns A pointer to the Protocol assosiated with this connection. + */ + class Protocol *getProtocol(); + +private: + /** + * A buffer to keep data read from the socket in. This is filled in by + * the function readInput, which is automatically called by the + * ConnectionManager whenever new data is ready. + */ + FlexBuf xInputBuf; + + /** + * A buffer to keep data that should be sent to the socket. This is filled + * in by using the AppendOutput functions and is sent to the socket using + * the writeOutput function, which is automatically called every cycle by + * the ConnectionManager when there is pending data. + */ + FlexBuf xOutputBuf; + + /** + * The socket that the user is connected to. This is not the same as the + * socket number of the listening socket, this is the unique socket on the + * system that the data is coming to. + */ + int nSocket; + + /** + * True=active connection, False=connection lost + */ + bool bActive; + + /** + * True=disconnect next cycle (after data is transmitted), Flse=keep going. + */ + bool bDisconnectMe; + + /** + * A pointer to a protocol handler that can automatically process the data + * in the buffers. This is optional if you use the connections on your own + * but reccomended if you use this with the rest of the ConnectionManager + * system. + */ + class Protocol *pProtocol; +}; + +#endif -- cgit v1.2.3