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 /** \file
  24     \brief senf::FileHandle public header
  25  */
  26
  27 #ifndef HH_FileHandle_
  28 #define HH_FileHandle_ 1
  29
  30 // Custom includes
  31 #include <memory> // std::auto_ptr
  32 #include "Utils/SafeBool.hh"
  33
  34 //#include "FileHandle.mpp"
  35 ///////////////////////////////hh.p////////////////////////////////////////
  36 #include "FileHandle.ih"
  37
  38 namespace senf {
  39
  40
  41     /** \brief Basic file handle wrapper
  42
  43         senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a
  44         minimal interface which does \e not include reading or writing (since some filehandles are
  45         not readable or writable or only using special function calls like sendto).
  46
  47         The FileHandle class provides handle/body handling and uses automatic reference
  48         counting. The senf::FileHandle istance is very lightweight and should be used like a
  49         built-in type.
  50
  51         \attention You should mostly pass around senf::FileHandle objects by \e value und not by
  52         reference.
  53
  54         The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to
  55         wrap any provider or consumer into a filehandle like interface using this wrapper. The
  56         wrapper will forward some calls directly to the underlying API without relying on virtual
  57         methods. This allows important members to be inlined.
  58
  59         It is not possible to use the senf::FileHandle class directly since it does not have any
  60         public constructor. The FileHandle class is however the baseclass of all handle classes of
  61         the socket library.
  62
  63         \section filehandle_new Writing senf::FileHandle derived classes
  64
  65         To build a new FileHandle type you need to derive from senf::FileHandle. The derived class
  66         will have to call the protocted FileHandle constructor passing a new senf::FileBody
  67         instance. This instance may either be a simple senf::FileBody or a class derived from
  68         senf::FileBody.
  69
  70         \todo Add public default constructor to allow declaration of (empty) senf::FileHandle
  71         variables.
  72      */
  73     class FileHandle
  74         : public SafeBool<FileHandle>
  75     {
  76     public:
  77         ///////////////////////////////////////////////////////////////////////////
  78         // Types
  79
  80         ///////////////////////////////////////////////////////////////////////////
  81         ///\name Structors and default members
  82         ///@{
  83
  84         // protected default constructor
  85         // default copy constructor
  86         // default copy assignment
  87         // default destructor
  88
  89         // no conversion constructors
  90
  91         ///@}
  92         ///////////////////////////////////////////////////////////////////////////
  93
  94         void close();                ///< Close filehandle
  95                                      /**< \throws senf::SystemException */
  96         void terminate();            ///< Close filehandle ignoring error conditions
  97
  98         bool readable() const;       ///< Check, wether a read on the handle would not block
  99                                      ///< (ignoring blocking state)
 100         void waitReadable() const;   ///< Wait, until read on the handle would not block (ignoring
 101                                      ///< blocking state)
 102         bool writeable() const;      ///< Check, wether a write on the handle would not block
 103                                      ///< (ignoring blocking state)
 104         void waitWriteable() const;  ///< Wait, until a write on the handle would not block
 105                                      ///< (ignoring blocking state)
 106
 107         bool blocking() const;       ///< Return current blocking state
 108         void blocking(bool status);  ///< Set blocking state
 109
 110         bool eof() const;            ///< Check EOF condition
 111                                      /**< Depending on the socket type, this might never return \p
 112                                         true.
 113
 114                                         This member is somewhat problematic performance wise if
 115                                         called frequently since it relies on virtual
 116                                         functions. However, since the eof() handling is extremely
 117                                         protocol dependent, a policy based implementation does not
 118                                         seam feasible. */
 119         bool valid() const;          ///< Check filehandle validity
 120                                      /**< Any operation besides valid() will fail on an invalid
 121                                         FileHandle */
 122
 123         bool boolean_test() const;  ///< Short for valid() && ! eof()
 124                                     /**< This is called when using a FileHandle instance in a boolen
 125                                        context
 126
 127                                        See the performance comments for the eof() member */
 128
 129         int fd() const;             ///< Return the raw FileHandle
 130
 131         static FileHandle cast_static(FileHandle handle);  /**< \internal */
 132         static FileHandle cast_dynamic(FileHandle handle); /**< \internal */
 133
 134     protected:
 135         explicit FileHandle(std::auto_ptr<FileBody> body);
 136                                     ///< create new FileHandle instance
 137                                     /**< The FileHandle instance will take over ownership over the
 138                                        given FileBody instance which must have been allocated using
 139                                        \c new. To configure the FileHandle behavior, A derived class
 140                                        may provide any class derived from FileBody here. */
 141
 142         FileBody & body();          ///< Access body
 143         FileBody const & body() const; ///< Access body in const context
 144         static FileBody & body(FileHandle & handle); ///< Access body of another FileHandle instance
 145         static FileBody const & body(FileHandle const & handle); ///< Access body of another
 146                                     ///< FileHandle instance in const context
 147
 148         void fd(int fd);            ///< Set raw filehandle
 149
 150     private:
 151         FileBody::ptr body_;
 152     };
 153
 154     int retrieve_filehandle(FileHandle handle);
 155
 156 }
 157
 158 ///////////////////////////////hh.e////////////////////////////////////////
 159 #include "FileHandle.cci"
 160 //#include "FileHandle.ct"
 161 //#include "FileHandle.cti"
 162 #endif
 163
 164 \f
 165 // Local Variables:
 166 // mode: c++
 167 // c-file-style: "senf"
 168 // fill-column: 100
 169 // End: