Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members

FXIOHandle.h

Go to the documentation of this file.
00001 /********************************************************************************
00002 *                                                                               *
00003 *                  Generic I/O object                                           *
00004 *                                                                               *
00005 *********************************************************************************
00006 * Copyright (C) 2003 by Mathew Robertson.   All Rights Reserved.                *
00007 *********************************************************************************
00008 * This library is free software; you can redistribute it and/or                 *
00009 * modify it under the terms of the GNU Lesser General Public                    *
00010 * License as published by the Free Software Foundation; either                  *
00011 * version 2.1 of the License, or (at your option) any later version.            *
00012 *                                                                               *
00013 * This library is distributed in the hope that it will be useful,               *
00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of                *
00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU             *
00016 * Lesser General Public License for more details.                               *
00017 *                                                                               *
00018 * You should have received a copy of the GNU Lesser General Public              *
00019 * License along with this library; if not, write to the Free Software           *
00020 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.    *
00021 ********************************************************************************/
00022 #ifndef FXIOHANDLE_H
00023 #define FXIOHANDLE_H
00024 
00025 #ifndef FXBASEOBJECT_H
00026 #include "FXBaseObject.h"
00027 #endif
00028 namespace FXEX {
00029 
00030 /**
00031  * FXIOhandle's move data around using this data structure
00032  */
00033 class FXAPI FXIOData {
00034 public:
00035   FXInputHandle  iohandle;  // the IO handle
00036   FXuchar       *data;      // raw data
00037   FXuint         no;        // the amount of data
00038   FXbool         oob;       // the data is Out-Of-Band data (not valid/used for some IO types)
00039 
00040 public:
00041   /// save structure to stream
00042   friend FXAPI FXStream& operator<< (FXStream& store,const FXIOData& d);
00043 
00044   /// load structure from stream
00045   friend FXAPI FXStream& operator>> (FXStream& store,FXIOData& d);
00046 
00047 public:
00048   /// Construct from existing IO handle
00049   FXIOData(FXInputHandle h=INVALID_HANDLE,FXbool outOfBand=FALSE);
00050 
00051   /// Construct to contain data
00052   FXIOData(FXuchar *d,FXuint n);
00053 
00054   /// dtor
00055   virtual ~FXIOData();
00056   };
00057 
00058 
00059 /**
00060  * This is the base class of all IO capabilities (sockets/files/serial-port).  It provides
00061  * generic IO handling capabilities.
00062  *
00063  * Notes:
00064  * - the write() and read() methods are in the public interface specifically to be flexible
00065  *   to the end programmer, though they shouldn't really need to use them directly.
00066  */
00067 class FXAPI FXIOHandle : public FXBaseObject {
00068   FXDECLARE (FXIOHandle)
00069 
00070   protected:
00071     FXInputHandle    iohandle;          // ... the IO handle ...
00072     FXint            code;              // status of object
00073     FXIOState        state;             // indicates the state of the IO handle
00074     FXint            readBufSize;       // the size of the read buffer
00075     FXIOData         writeBuffer;       // data waiting to be written
00076     FXIOData        *readBuffer;        // data just been read
00077     FXint            activityPeriod;    // the period between handle activity events
00078 
00079   protected:
00080     /// helper; to write data
00081     FXbool writeAgain();
00082 
00083     /// helper; to add this IO handle to the FXApp watch list
00084     FXbool addInput();
00085 
00086   public:
00087     enum {
00088       ID_IOHANDLE=FXBaseObject::ID_LAST,
00089       ID_WRITE,
00090       ID_WRITE_OOB,
00091       ID_LAST
00092       };
00093 
00094   public:
00095     long onRead(FXObject*,FXSelector,void*);
00096     long onWrite(FXObject*,FXSelector,void*);
00097     long onExcept(FXObject*,FXSelector,void*);
00098     long onActivityTimeout(FXObject*,FXSelector,void*);
00099     long onIORead(FXObject*,FXSelector,void*);
00100     long onIOWrite(FXObject*,FXSelector,void*);
00101     long onIOExcept(FXObject*,FXSelector,void*);
00102     long onIOConnect(FXObject*,FXSelector,void*);
00103     long onCmdWrite(FXObject*,FXSelector,void*);
00104     long onCmdGetIntValue(FXObject*,FXSelector,void*);
00105     long onOpened(FXObject*,FXSelector,void*);
00106     long onClose(FXObject*,FXSelector,void*);
00107     long onClosed(FXObject*,FXSelector,void*);
00108     long onDestroy(FXObject*,FXSelector,void*);
00109     long onData(FXObject*,FXSelector,void*);
00110 
00111   protected:
00112     /// for de-serialisation
00113     FXIOHandle();
00114 
00115     /// close the underlying operating system handle
00116     virtual void closehandle();
00117 
00118     /// instanciates this object
00119     virtual FXIOHandle* newInstance(FXInputHandle h);
00120 
00121     /** Create an IO handle - child classes should overload the
00122      *  open(), close(), errorClose(), read() and write()
00123      *  methods to implement appropriate behaviour
00124      */
00125     FXIOHandle(FXApp *a,FXObject *tgt=NULL,FXSelector sel=0);
00126 
00127   public:
00128     /// IO Handle equality is just the test to see if the OS handles are the same
00129     friend FXAPI FXbool operator==(const FXIOHandle& h1, const FXIOHandle& h2);
00130     friend FXAPI FXbool operator!=(const FXIOHandle& h1, const FXIOHandle& h2);
00131 
00132   public:
00133     /// Use an existing IO handle, adding it to the FXApp event loop
00134     FXIOHandle(FXInputHandle h,FXApp *a,FXObject *tgt=NULL,FXSelector sel=0);
00135 
00136     /// create resources
00137     virtual void create();
00138 
00139     /// detach resource
00140     virtual void detach();
00141 
00142     /// destroy resource
00143     virtual void destroy();
00144 
00145     /// get the status of the last action (ie returns errno or something similar)
00146     FXint status() { return code; }
00147 
00148     /// reset the status value
00149     void resetStatus() { code=FXIOStatusOk; }
00150 
00151     /// get the state of the socket
00152     FXIOState getState() { return state; }
00153 
00154     /// simple indication if handle is open
00155     FXbool opened();
00156 
00157     /// simple indication if handle is closed
00158     FXbool closed();
00159 
00160     /// return the file descriptor / event handle
00161     virtual FXInputHandle getHandle() { return iohandle; }
00162 
00163     /// set the size of the minimum read chunk
00164     /// ie use this to optimise the number of reads vs. memory used
00165     void setBuf(FXint size) { readBufSize=size; }
00166 
00167     /// get the non-blocking state of the connection
00168     FXbool nonBlocking();
00169 
00170     /// set the connection to the non-blocking state
00171     FXbool nonBlocking(FXbool nonBlock);
00172 
00173     /// Open-up/create connection
00174     virtual FXbool open();
00175 
00176     /// Close down the connection
00177     virtual void close();
00178 
00179     /// Close down the connection, sending the child/target a SEL_DESTROY message
00180     /// This is used internally when there are errors on the IO handle
00181     virtual void errorClose();
00182 
00183     /**
00184      * Get some data from the IO handle
00185      * derived classes should implement IO specific read()
00186      */
00187     virtual FXint read(FXuchar *data,FXint len,FXbool outOfBand=FALSE);
00188 
00189     /**
00190      * Write some data over the IO handle - can write out of band data if required
00191      * derived classes should implement IO specific write()
00192      */
00193     virtual FXint write(FXuchar *data,FXint n,FXbool outOfBand=FALSE);
00194 
00195     /// read the IO handle and generate FOX events
00196     FXbool readData(FXbool outOfBand=FALSE);
00197 
00198     /**
00199      * Write the data out of the IO handle.
00200      * May not send all the data at once but call always completes without blocking
00201      * re-schedules any remaing data to send later
00202      */
00203     FXbool writeData(FXIOData *d);
00204 
00205     /**
00206      * Returns the data just received, as a text string
00207      * Note: this call is _only_ valid 'during the handle' of the SEL_COMMAND event
00208      *       by the child/target, at all other times this returns FXString::null
00209      */
00210     FXString getText() const;
00211 
00212     /// writes the string to the IO handle
00213     void setText(const FXString& message);
00214 
00215     /**
00216      * Set an activity timer.  Each time data is read-from / written-to the handle,
00217      * the timer is reset.  If the timer expires, no activity has occurred.  A value
00218      * of zero, disables the timer.
00219      */
00220     void setActivityTimeout(FXint ms=0);
00221 
00222     /**
00223      * Duplicate this handle onto another handle, defaults to OS assigned value 
00224      * ie the user can ask for the duplicate to be mapped onto a specific IO value
00225      */
00226     virtual FXIOHandle* duplicate(FXInputHandle newHandle=INVALID_HANDLE);
00227 
00228     /// save object to stream
00229     virtual void save(FXStream& store) const;
00230 
00231     /// load object from stream
00232     virtual void load(FXStream& store);
00233 
00234     /// dtor
00235     virtual ~FXIOHandle();
00236   };
00237 
00238 } // namespace FXEX
00239 #endif // FXIOHANDLE_H