Socket/FileHandle.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <stefan.bund@fokus.fraunhofer.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 #ifndef HH_FileHandle_
  24 #define HH_FileHandle_ 1
  25
  26 // Custom includes
  27 #include <memory> // std::auto_ptr
  28 #include "Utils/SafeBool.hh"
  29
  30 //#include "FileHandle.mpp"
  31 ///////////////////////////////hh.p////////////////////////////////////////
  32 #include "FileHandle.ih"
  33
  34 namespace senf {
  35
  36
  37     /** \brief Basic file handle wrapper
  38
  39         senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a
  40         minimal interface which does \e not include reading or writing (since some filehandles are
  41         not readable or writable or only using special function calls like sendto).
  42
  43         The FileHandle class provides handle/body handling and uses automatic reference
  44         counting. The senf::FileHandle istance is very lightweight and should be used like a
  45         built-in type.
  46
  47         \attention You should mostly pass around senf::FileHandle objects by \e value und not by
  48         reference.
  49
  50         The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to
  51         wrap any provider or consumer into a filehandle like interface using this wrapper. The
  52         wrapper will forward some calls directly to the underlying API without relying on virtual
  53         methods. This allows important members to be inlined.
  54
  55         It is not possible to use the senf::FileHandle class directly since it does not have any
  56         public constructor. The FileHandle class is however the baseclass of all handle classes of
  57         the socket library.
  58
  59         \section filehandle_new Writing senf::FileHandle derived classes
  60
  61         To build a new FileHandle type you need to derive from senf::FileHandle. The derived class
  62         will have to call the protocted FileHandle constructor passing a new senf::FileBody
  63         instance. This instance may either be a simple senf::FileBody or a class derived from
  64         senf::FileBody.
  65
  66         \todo Add public default constructor to allow declaration of (empty) senf::FileHandle
  67         variables.
  68      */
  69     class FileHandle
  70         : public SafeBool<FileHandle>
  71     {
  72     public:
  73         ///////////////////////////////////////////////////////////////////////////
  74         // Types
  75
  76         ///////////////////////////////////////////////////////////////////////////
  77         ///\name Structors and default members
  78         ///@{
  79
  80         // protected default constructor
  81         // default copy constructor
  82         // default copy assignment
  83         // default destructor
  84
  85         // no conversion constructors
  86
  87         ///@}
  88         ///////////////////////////////////////////////////////////////////////////
  89
  90         void close();                ///< Close filehandle
  91                                      /**< \throws senf::SystemException */
  92         void terminate();            ///< Close filehandle ignoring error conditions
  93
  94         bool readable() const;       ///< Check, wether a read on the handle would not block
  95                                      ///< (ignoring blocking state)
  96         void waitReadable() const;   ///< Wait, until read on the handle would not block (ignoring
  97                                      ///< blocking state)
  98         bool writeable() const;      ///< Check, wether a write on the handle would not block
  99                                      ///< (ignoring blocking state)
 100         void waitWriteable() const;  ///< Wait, until a write on the handle would not block
 101                                      ///< (ignoring blocking state)
 102
 103         bool blocking() const;       ///< Return current blocking state
 104         void blocking(bool status);  ///< Set blocking state
 105
 106         bool eof() const;            ///< Check EOF condition
 107                                      /**< Depending on the socket type, this might never return \p
 108                                         true */
 109         bool valid() const;          ///< Check filehandle validity
 110                                      /**< Any operation besides valid() will fail on an invalid
 111                                         FileHandle */
 112
 113         bool boolean_test() const;  ///< Short for valid() && ! eof()
 114                                     /**< This is called when using a FileHandle instance in a boolen
 115                                        context */
 116
 117         int fd() const;             ///< Return the raw FileHandle
 118
 119         static FileHandle cast_static(FileHandle handle);  ///< \internal
 120         static FileHandle cast_dynamic(FileHandle handle); ///< \internal
 121
 122     protected:
 123         explicit FileHandle(std::auto_ptr<FileBody> body);
 124                                     ///< create new FileHandle instance
 125                                     /**< The FileHandle instance will take over ownership over the
 126                                        given FileBody instance which must have been allocated using
 127                                        \c new. To configure the FileHandle behavior, A derived class
 128                                        may provide any class derived from FileBody here. */
 129
 130         FileBody & body();          ///< Access body
 131         FileBody const & body() const; ///< Access body in const context
 132         static FileBody & body(FileHandle & handle); ///< Access body of another FileHandle instance
 133         static FileBody const & body(FileHandle const & handle); ///< Access body of another
 134                                     ///< FileHandle instance in const context
 135
 136         void fd(int fd);            ///< Set raw filehandle
 137
 138     private:
 139         FileBody::ptr body_;
 140     };
 141
 142     int retrieve_filehandle(FileHandle handle);
 143
 144 }
 145
 146 ///////////////////////////////hh.e////////////////////////////////////////
 147 #include "FileHandle.cci"
 148 //#include "FileHandle.ct"
 149 //#include "FileHandle.cti"
 150 #endif
 151
 152 \f
 153 // Local Variables:
 154 // mode: c++
 155 // c-file-style: "senf"
 156 // fill-column: 100
 157 // End: