simgear/io/iochannel.hxx

   1 /**
   2  * \file iochannel.hxx
   3  * High level IO channel base class.
   4  */
   5
   6 // Written by Curtis Olson, started November 1999.
   7 //
   8 // Copyright (C) 1999  Curtis L. Olson - http://www.flightgear.org/~curt
   9 //
  10 // This program is free software; you can redistribute it and/or
  11 // modify it under the terms of the GNU General Public License as
  12 // published by the Free Software Foundation; either version 2 of the
  13 // License, or (at your option) any later version.
  14 //
  15 // This program is distributed in the hope that it will be useful, but
  16 // WITHOUT ANY WARRANTY; without even the implied warranty of
  17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18 // General Public License for more details.
  19 //
  20 // You should have received a copy of the GNU General Public License
  21 // along with this program; if not, write to the Free Software
  22 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  23 //
  24 // $Id$
  25
  26
  27 #ifndef _IOCHANNEL_HXX
  28 #define _IOCHANNEL_HXX
  29
  30
  31 #include <simgear/compiler.h>
  32
  33 #define SG_IO_MAX_MSG_SIZE 16384
  34
  35 /**
  36  * Specify if this is a read (IN), write (OUT), or r/w (BI) directional
  37  * channel
  38  */
  39 enum SGProtocolDir {
  40     SG_IO_NONE = 0,
  41     SG_IO_IN = 1,
  42     SG_IO_OUT = 2,
  43     SG_IO_BI = 3
  44 };
  45
  46 /**
  47  * Specify the channel type
  48  */
  49 enum SGChannelType {
  50     sgFileType = 0,
  51     sgSerialType = 1,
  52     sgSocketType = 2
  53 };
  54
  55
  56 /**
  57  * The SGIOChannel base class provides a consistent method for
  58  * applications to communication through various mediums. By providing
  59  * a base class with multiple derived classes, and application such as
  60  * FlightGear can implement a way to speak any protocol via any kind
  61  * of I/O channel.
  62  *
  63  * All of the SGIOChannel derived classes have exactly the same usage
  64  * interface once an instance has been created.
  65  *
  66  */
  67 class SGIOChannel {
  68
  69     SGChannelType type;
  70     SGProtocolDir dir;
  71     bool valid;
  72
  73 public:
  74
  75     /** Constructor */
  76     SGIOChannel();
  77
  78     /** Destructor */
  79     virtual ~SGIOChannel();
  80
  81     /** Open a channel.
  82      * @param d channel communication "direction"
  83      * Direction can be one of:
  84      *  - SG_IO_IN - data will be flowing into this object to the application.
  85      *  - SG_IO_OUT - data will be flowing out of this object from the
  86      *                application.
  87      *  - SG_IO_BI - data will be flowing in both directions.
  88      *  - SG_IO_NONE - data will not be flowing in either direction.
  89      *                 This is here for the sake of completeness.
  90      * @return result of open
  91      */
  92     virtual bool open( const SGProtocolDir d );
  93
  94     /**
  95      * The read() method is modeled after the read() Unix system
  96      * call. You must provide a pointer to a character buffer that has
  97      * enough allocated space for your potential read. You can also
  98      * specify the maximum number of bytes allowed for this particular
  99      * read. The actual number of bytes read is returned.  You are
 100      * responsible to ensure that the size of buf is large enough to
 101      * accomodate your input message
 102      * @param buf a char pointer to your input buffer
 103      * @param length max number of bytes to read
 104      * @return number of bytes read
 105      */
 106     virtual int read( char *buf, int length );
 107
 108     /**
 109      * The readline() method is similar to read() except that it will
 110      * stop at the first end of line encountered in the input buffer.
 111      * @param buf a char pointer to your input buffer
 112      * @param length max number of bytes to read
 113      * @return number of bytes read
 114      */
 115     virtual int readline( char *buf, int length );
 116
 117
 118     /**
 119      * The write() method is modeled after the write() Unix system
 120      * call and is analogous to the read() method. You provide a
 121      * pointer to a buffer of data, and then length of that data to be
 122      * written out. The number of bytes written is returned.
 123      * @param buf a char pointer to your output buffer
 124      * @param length number of bytes to write
 125      * @return number of bytes written
 126      */
 127     virtual int write( const char *buf, const int length );
 128
 129     /**
 130      * The writestring() method is a simple wrapper that will
 131      * calculate the length of a null terminated character array and
 132      * write it to the output channel.
 133      * @param buf a char pointer to your output buffer
 134      * @return number of bytes written
 135      */
 136     virtual int writestring( const char *str );
 137
 138     /**
 139      * The close() method is modeled after the close() Unix system
 140      * call and will close an open device. You should call this method
 141      * when you are done using your IO class, before it is destructed.
 142      * @return result of close
 143      */
 144     virtual bool close();
 145
 146     /**
 147      * The eof() method returns true if end of file has been reached
 148      * in a context where that makes sense.  Otherwise it returns
 149      * false.
 150      * @return result of eof check
 151      */
 152     virtual bool eof() const;
 153
 154     inline void set_type( SGChannelType t ) { type = t; }
 155     inline SGChannelType get_type() const { return type; }
 156
 157     inline void set_dir( const SGProtocolDir d ) { dir = d; }
 158     inline SGProtocolDir get_dir() const { return dir; }
 159     inline bool isvalid() const { return valid; }
 160     inline void set_valid( const bool v ) { valid = v; }
 161 };
 162
 163
 164 #endif // _IOCHANNEL_HXX
 165
 166