4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
7 // Version 1.0 (the "License"); you may not use this file except in compliance
8 // with the License. You may obtain a copy of the License at
9 // http://senf.berlios.de/license.html
11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
12 // but modifies the Mozilla Public License Version 1.1.
13 // See the full license text for the amendments.
15 // Software distributed under the License is distributed on an "AS IS" basis,
16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
17 // for the specific language governing rights and limitations under the License.
19 // The Original Code is Fraunhofer FOKUS code.
21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
23 // All Rights Reserved.
26 // Stefan Bund <g0dil@berlios.de>
29 \brief FileHandle internal header
32 #ifndef IH_SENF_Socket_FileHandle_
33 #define IH_SENF_Socket_FileHandle_ 1
36 #include <boost/intrusive_ptr.hpp>
37 #include <senf/Utils/intrusive_refcount.hh>
38 #include <senf/Utils/pool_alloc_mixin.hh>
40 //-/////////////////////////////////////////////////////////////////////////////////////////////////
46 /** \brief FileHandle referenced body
50 The senf::FileBody class forms the body part of the handle/body structure of the FileHandle
51 interface. It manages the FileHandle data and is referenced by senf::FileHandle. It is
52 automatically managed using reference counting.
54 Since the senf::FileHandle class forwards most calls directly to the underlying
55 senf::FileBody instance, most members are documented in senf::FileHandle.
57 \section filebody_new Writing senf::FileBody derived classes
59 It is possible to write customized senf::FileBody derived body implementations. This
60 implementation can then be used be a senf::FileHandle derived class to customize the
61 FileHandle behavior. Handling the body directly by the handle class ensures, that no invalid
62 handles can be created (a senf::FileHandle derived handle expecting a specific body type but
63 pointing to a different body type).
65 To customize the behavior, a virtual interface is provided. This interface only covers some
66 basic functionality which is only used infrequently during the lifetime of a FileHandle
69 \attention Whenever a new class is derived from FileBody which adds new members, this class
70 \e must also derive from senf::pool_alloc_mixin
73 : public senf::intrusive_refcount,
74 public senf::pool_alloc_mixin<FileBody>
77 //-/////////////////////////////////////////////////////////////////////////////////////////
80 typedef boost::intrusive_ptr<FileBody> ptr;
82 //-/////////////////////////////////////////////////////////////////////////////////////////
83 ///\name Structors and default members
86 explicit FileBody(int fd=-1); ///< Create new instance
87 /**< You need to pass a real file descriptor to this
88 constructor not some arbitrary id even if you overload
89 all the virtual members. If the file descriptor is -1 the
90 resulting body/handle is not valid() */
93 // NO DESTRUCTOR HERE (that is, only an empty virtual destructor) - destructors and virtual
94 // functions don't mix. What would be in the the destructor is in 'destroyClose()' which is
95 // called from FileHandle::~FileHandle() *before* the last handle dies.
98 // no conversion constructors
101 //-/////////////////////////////////////////////////////////////////////////////////////////
112 bool readable() const;
113 bool waitReadable(senf::ClockService::clock_type timeout) const;
114 bool writeable() const;
115 bool waitWriteable(senf::ClockService::clock_type timeout) const;
116 bool oobReadable() const;
117 bool waitOOBReadable(senf::ClockService::clock_type timeout) const;
119 bool blocking() const;
120 void blocking(bool status);
126 //-/////////////////////////////////////////////////////////////////////////////////////////
127 // Virtual interface for subclasses to override
129 virtual void v_close(); ///< Called to close the file descriptor
130 /**< You should probably always call the global ::close()
131 function in this member, however you might want to do
132 some additional cleanup here. If the operation fails, you
133 are allowed to throw (preferably a
134 senf::SystemException).
136 \throws senf::SystemException */
137 virtual void v_terminate(); ///< Called to forcibly close the file descriptor
138 /**< This member is called by the destructor (and by
139 terminate()) to close the descriptor. This member must \e
140 never throw, it should probably just ignore error
141 conditions (there's not much else you can do) */
142 virtual bool v_eof() const; ///< Called by eof()
143 virtual bool v_valid() const; ///< Called by valid()
144 /**< This member is only called, if the file descriptor is
150 bool pollCheck(int fd, bool incoming, int timeout, bool oob=false) const;
157 //-/////////////////////////////////////////////////////////////////////////////////////////////////
164 // c-file-style: "senf"
165 // indent-tabs-mode: nil
166 // ispell-local-dictionary: "american"
167 // compile-command: "scons -u test"
168 // comment-column: 40