Socket/FileHandle.ih

   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 FileHandle internal header
  25  */
  26
  27 #ifndef IH_FileHandle_
  28 #define IH_FileHandle_ 1
  29
  30 // Custom includes
  31 #include <boost/intrusive_ptr.hpp>
  32 #include "Utils/intrusive_refcount.hh"
  33
  34 ///////////////////////////////ih.p////////////////////////////////////////
  35
  36 namespace senf {
  37
  38
  39     /** \brief FileHandle referenced body
  40
  41         \internal
  42
  43         The senf::FileBody class formes the body part of the handle/body structure of the FileHandle
  44         interface. It manages the FileHandle data and is referenced by senf::FileHandle. It is
  45         automatically managed using reference counting.
  46
  47         Since the senf::FileHandle class forwards most calls directly to the underlying
  48         senf::FileBody instance, most members are documented in senf::FileHandle.
  49
  50         \section filebody_new Writing senf::FileBody derived classes
  51
  52         It is possible to write customized senf::FileBody derived body implementations. This
  53         implementation can then be used be a senf::FileHandle derived class to customize the
  54         FileHandle behavior. Handling the body directly by the handle class ensures, that no invalid
  55         handles can be created (a senf::FileHandle derived handle expecting a specific body type but
  56         pointing to a different body type).
  57
  58         To customize the behavior, a virtual interface is provided. This interface only covers some
  59         basic funcionality which is only used infrequently during the lifetime of a FileHandle
  60         instance.
  61
  62       */
  63     class FileBody
  64         : public senf::intrusive_refcount
  65     {
  66     public:
  67         ///////////////////////////////////////////////////////////////////////////
  68         // Types
  69
  70         typedef boost::intrusive_ptr<FileBody> ptr;
  71
  72         ///////////////////////////////////////////////////////////////////////////
  73         ///\name Structors and default members
  74         ///@{
  75
  76         explicit FileBody(int fd=-1);   ///< Create new instance
  77                                         /**< You need to pass a real file descriptor to this
  78                                            constructor not some arbitrary id even if you overload
  79                                            all the virtual members. If the file descriptor is -1 the
  80                                            resulting body/handle is not valid() */
  81         virtual ~FileBody();
  82
  83         // no copy
  84         // no conversion constructors
  85
  86         ///@}
  87         ///////////////////////////////////////////////////////////////////////////
  88
  89         int fd() const;
  90         void fd(int fd);
  91
  92         void close();
  93         void terminate();
  94
  95         bool readable() const;
  96         void waitReadable() const;
  97         bool writeable() const;
  98         void waitWriteable() const;
  99
 100         bool blocking() const;
 101         void blocking(bool status);
 102
 103         bool eof() const;
 104         bool valid() const;
 105
 106     private:
 107         ///////////////////////////////////////////////////////////////////////////
 108         // Virtual interface for subclasses to override
 109
 110         virtual void v_close();         ///< Called to close the file descriptor
 111                                         /**< You should probably always call the global ::close()
 112                                            function in this member, however you might want to do
 113                                            some additional cleanup here. If the operation fails, you
 114                                            are allowed to throw (preferably a
 115                                            senf::SystemException).
 116
 117                                         \throws senf::SystemException */
 118         virtual void v_terminate();     ///< Called to forcibly close the file descriptor
 119                                         /**< This member is called by the destructor (and by
 120                                            terminate()) to close the descriptor. This member must \e
 121                                            never throw, it should probably just ignore error
 122                                            conditions (there's not much else you can do) */
 123         virtual bool v_eof() const;     ///< Called by eof()
 124         virtual bool v_valid() const;   ///< Called by valid()
 125                                         /**< This member is only called, if the file descriptor is
 126                                            not -1 */
 127
 128     protected:
 129
 130     private:
 131         bool pollCheck(int fd, bool incoming, bool block=false) const;
 132
 133         int fd_;
 134     };
 135
 136 }
 137
 138 ///////////////////////////////ih.e////////////////////////////////////////
 139 #endif
 140
 141 \f
 142 // Local Variables:
 143 // mode: c++
 144 // fill-column: 100
 145 // c-file-style: "senf"
 146 // indent-tabs-mode: nil
 147 // ispell-local-dictionary: "american"
 148 // End: