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 public header
32 /** \defgroup handle_group The Handle Hierarchy
34 \diaimage FhHierarchy.dia
36 The senf::FileHandle class is the base of a hierarchy of socket handle classes (realized as
37 templates). These classes provide an interface to the complete socket API. While going down the
38 inheritance hierarchy, the interface will be more and more complete.
40 The most complete interface is provided by senf::ProtocolClientSocketHandle and
41 senf::ProtocolServerSocketHandle. The template Arguments specifies the Protocol class of the
42 underlying socket type. These are the \e only classes having public constructors and are
43 therefore the only classes, which may be created by the library user. You will normally use
44 these classes by naming a specific socket typedef (e.g. senf::TCPv4ClientSocketHandle).
46 However, to aid writing flexible and generic code, the socket library provides the
47 senf::ClientSocketHandle and senf::ServerSocketHandle class templates. These templates implement
48 a family of closely related classes based on the specification of the socket policy. This policy
49 specification may be \e incomplete (see below). Instances of
50 senf::ClientSocketHandle/senf::ServerSocketHandle can be assigned and converted to different
51 ClientSocketHandle/ServerSocketHandle types as long as the policy specifications are compatible.
53 \attention It is very important, to (almost) always pass the socket handle <em>by
54 value</em>. The socket handle is a very lightweight class and designed to be used like an
55 ordinary built-in type. This is very important in combination with the policy interface.
57 \note The FileHandle hierarchy below the SocketHandle template is \e not meant to be user
58 extensible. To add new socket types, you should introduce new protocol and/or policy classes,
59 the SocketHandle classes should not be changed.
62 #ifndef HH_SENF_Socket_FileHandle_
63 #define HH_SENF_Socket_FileHandle_ 1
66 #include <memory> // std::auto_ptr
67 #include <senf/Utils/safe_bool.hh>
68 #include <senf/Scheduler/ClockService.hh>
70 //#include "FileHandle.mpp"
71 //-/////////////////////////////////////////////////////////////////////////////////////////////////
72 #include "FileHandle.ih"
76 /// \addtogroup handle_group
79 /** \brief Basic file handle wrapper
81 senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a
82 minimal interface which does \e not include reading or writing (since some filehandles are
83 not readable or writable or only using special function calls like sendto).
85 The FileHandle class provides handle/body handling and uses automatic reference
86 counting. The senf::FileHandle instance is very lightweight and should be used like a
89 \attention You should mostly pass around senf::FileHandle objects by \e value and not by
92 The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to
93 wrap any provider or consumer into a filehandle like interface using this wrapper. The
94 wrapper will forward some calls directly to the underlying API without relying on virtual
95 methods. This allows important members to be inlined.
97 It is not possible to use the senf::FileHandle class directly since it does not have any
98 public constructor. The FileHandle class is however the baseclass of all handle classes of
101 \section filehandle_new Writing senf::FileHandle derived classes
103 To build a new FileHandle type you need to derive from senf::FileHandle. The derived class
104 will have to call the protected FileHandle constructor passing a new senf::FileBody
105 instance. This instance may either be a simple senf::FileBody or a class derived from
109 : public safe_bool<FileHandle>
112 //-////////////////////////////////////////////////////////////////////////
115 //-////////////////////////////////////////////////////////////////////////
116 ///\name Structors and default members
122 // my default constructor
123 // default copy constructor
124 // default copy assignment
125 // default destructor
127 // no conversion constructors
130 //-////////////////////////////////////////////////////////////////////////
132 void close(); ///< Close filehandle
133 /**< \throws senf::SystemException */
134 void terminate(); ///< Close filehandle ignoring error conditions
136 bool readable() const; ///< Check, whether a read on the handle would not block
137 ///< (ignoring blocking state)
138 bool waitReadable(senf::ClockService::clock_type timeout = -1) const;
139 ///< Wait, until read on the handle would not block (ignoring
141 /**< \param[in] timeout max time to wait, default is to wait
143 \returns \c true, if handle became readable or \c false on
145 bool writeable() const; ///< Check, whether a write on the handle would not block
146 ///< (ignoring blocking state)
147 bool waitWriteable(senf::ClockService::clock_type timeout = -1) const;
148 ///< Wait, until a write on the handle would not block
149 ///< (ignoring blocking state)
150 /**< \param[in] timeout max time to wait, default is to wait
152 \returns \c true, if handle became writable or \c false on
154 bool oobReadable() const; ///< Check, whether a read of prioritized data on the handle
155 ///< would not block (ignoring blocking state)
156 bool waitOOBReadable(senf::ClockService::clock_type timeout = -1) const;
157 ///< Wait, until read of prioritized data on the handle does
158 ///< not block (ignoring blocking state)
159 /**< \param[in] timeout max time to wait, default is to wait
161 \returns \c true, if handle became readable for
162 out-of-band data or \c false on timeout. */
164 bool blocking() const; ///< Return current blocking state
165 void blocking(bool status); ///< Set blocking state
167 bool eof() const; ///< Check EOF condition
168 /**< Depending on the socket type, this might never return \p
171 This member is somewhat problematic performance wise if
172 called frequently since it relies on virtual
173 functions. However, since the eof() handling is extremely
174 protocol dependent, a policy based implementation does not
176 bool valid() const; ///< Check filehandle validity
177 /**< Any operation besides valid() will fail on an invalid
180 bool boolean_test() const; ///< Short for valid() && ! eof()
181 /**< This is called when using a FileHandle instance in a boolean
184 See the performance comments for the eof() member */
186 int fd() const; ///< Return the raw FileHandle
188 static FileHandle cast_static(FileHandle handle); /**< \internal */
189 static FileHandle cast_dynamic(FileHandle handle); /**< \internal */
192 explicit FileHandle(std::auto_ptr<FileBody> body);
193 ///< create new FileHandle instance
194 /**< The FileHandle instance will take over ownership over the
195 given FileBody instance which must have been allocated using
196 \c new. To configure the FileHandle behavior, A derived class
197 may provide any class derived from FileBody here. */
199 explicit FileHandle(FileBody::ptr body);
201 FileBody & body(); ///< Access body
202 FileBody const & body() const; ///< Access body in const context
203 static FileBody & body(FileHandle & handle); ///< Access body of another FileHandle instance
204 static FileBody const & body(FileHandle const & handle); ///< Access body of another
205 ///< FileHandle instance in const context
207 void fd(int fd); ///< Set raw filehandle
212 friend class FileBody;
215 /** \brief Adapt FileHandle to senf::scheduler
216 \related senf::FileHandle
220 This function will be called by the Scheduler to retrieve the file descriptor of the
223 int retrieve_filehandle(FileHandle handle);
229 //-/////////////////////////////////////////////////////////////////////////////////////////////////
230 #include "FileHandle.cci"
231 //#include "FileHandle.ct"
232 //#include "FileHandle.cti"
239 // c-file-style: "senf"
240 // indent-tabs-mode: nil
241 // ispell-local-dictionary: "american"
242 // compile-command: "scons -u test"
243 // comment-column: 40