4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
6 // Stefan Bund <stefan.bund@fokus.fraunhofer.de>
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.
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.
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.
24 \brief FileHandle public header
27 /** \defgroup handle_group The Handle Hierarchy
29 \image html FhHierarchy.png
31 The senf::FileHandle class is the base of a hierarchy of socket
32 handle classes (realized as templates). These classes provide an
33 interface to the complete socket API. While going down the
34 inheritance hierarchy, the interface will be more and more
37 The most complete interface is provided by
38 senf::ProtocolClientSocketHandle and
39 senf::ProtocolServerSocketHandle. The template Arguments specifies
40 the Protocol class of the underlying socket type. These are the
41 \e only classes having public constructors and are therefore the
42 only classes, which may be created by the library user. You will
43 normally use these classes by naming a specific socket typedef
44 (e.g. senf::TCPv4ClientSocketHandle).
46 However, to aid writing flexible and generic code, the socket
47 library provides the senf::ClientSocketHandle and
48 senf::ServerSocketHandle class templates. These templates
49 implement a family of closely related classes based on the
50 specification of the socket policy. This policy specification may
51 be \e incomplete (see below). Instances of
52 senf::ClientSocketHandle/senf::ServerSocketHandle can be assigned
53 and converted to different ClientSocketHandle/ServerSocketHandle
54 types as long as the policy specifications are compatible.
56 \attention It is very important, to (almost) always pass the socket
57 handle <em>by value</em>. The socket handle is a very lightweight
58 class and designed to be used like an ordinary built-in type. This
59 is very important in combination with the policy interface.
61 \note The FileHandle hierarchy below the SocketHandle template is
62 \e not meant to be user extensible. To add new socket types, you
63 should introduce new protocol and/or policy classes, the
64 SocketHandle classes should not be changed.
67 #ifndef HH_FileHandle_
68 #define HH_FileHandle_ 1
71 #include <memory> // std::auto_ptr
72 #include "Utils/SafeBool.hh"
74 //#include "FileHandle.mpp"
75 ///////////////////////////////hh.p////////////////////////////////////////
76 #include "FileHandle.ih"
80 /// \addtogroup handle_group
83 /** \brief Basic file handle wrapper
85 senf::FileHandle provides a simple wrapper for arbitrary file handles. It exposes only a
86 minimal interface which does \e not include reading or writing (since some filehandles are
87 not readable or writable or only using special function calls like sendto).
89 The FileHandle class provides handle/body handling and uses automatic reference
90 counting. The senf::FileHandle instance is very lightweight and should be used like a
93 \attention You should mostly pass around senf::FileHandle objects by \e value and not by
96 The FileHandle abstraction is only applicable to real filehandles. It is \e not possible to
97 wrap any provider or consumer into a filehandle like interface using this wrapper. The
98 wrapper will forward some calls directly to the underlying API without relying on virtual
99 methods. This allows important members to be inlined.
101 It is not possible to use the senf::FileHandle class directly since it does not have any
102 public constructor. The FileHandle class is however the baseclass of all handle classes of
105 \section filehandle_new Writing senf::FileHandle derived classes
107 To build a new FileHandle type you need to derive from senf::FileHandle. The derived class
108 will have to call the protected FileHandle constructor passing a new senf::FileBody
109 instance. This instance may either be a simple senf::FileBody or a class derived from
112 \fixme Add public default constructor to allow declaration of (empty) senf::FileHandle
116 : public SafeBool<FileHandle>
119 ///////////////////////////////////////////////////////////////////////////
122 ///////////////////////////////////////////////////////////////////////////
123 ///\name Structors and default members
126 // protected default constructor
127 // default copy constructor
128 // default copy assignment
129 // default destructor
131 // no conversion constructors
134 ///////////////////////////////////////////////////////////////////////////
136 void close(); ///< Close filehandle
137 /**< \throws senf::SystemException */
138 void terminate(); ///< Close filehandle ignoring error conditions
140 bool readable() const; ///< Check, whether a read on the handle would not block
141 ///< (ignoring blocking state)
142 void waitReadable() const; ///< Wait, until read on the handle would not block (ignoring
144 bool writeable() const; ///< Check, whether a write on the handle would not block
145 ///< (ignoring blocking state)
146 void waitWriteable() const; ///< Wait, until a write on the handle would not block
147 ///< (ignoring blocking state)
149 bool blocking() const; ///< Return current blocking state
150 void blocking(bool status); ///< Set blocking state
152 bool eof() const; ///< Check EOF condition
153 /**< Depending on the socket type, this might never return \p
156 This member is somewhat problematic performance wise if
157 called frequently since it relies on virtual
158 functions. However, since the eof() handling is extremely
159 protocol dependent, a policy based implementation does not
161 bool valid() const; ///< Check filehandle validity
162 /**< Any operation besides valid() will fail on an invalid
165 bool boolean_test() const; ///< Short for valid() && ! eof()
166 /**< This is called when using a FileHandle instance in a boolean
169 See the performance comments for the eof() member */
171 int fd() const; ///< Return the raw FileHandle
173 static FileHandle cast_static(FileHandle handle); /**< \internal */
174 static FileHandle cast_dynamic(FileHandle handle); /**< \internal */
177 explicit FileHandle(std::auto_ptr<FileBody> body);
178 ///< create new FileHandle instance
179 /**< The FileHandle instance will take over ownership over the
180 given FileBody instance which must have been allocated using
181 \c new. To configure the FileHandle behavior, A derived class
182 may provide any class derived from FileBody here. */
184 FileBody & body(); ///< Access body
185 FileBody const & body() const; ///< Access body in const context
186 static FileBody & body(FileHandle & handle); ///< Access body of another FileHandle instance
187 static FileBody const & body(FileHandle const & handle); ///< Access body of another
188 ///< FileHandle instance in const context
190 void fd(int fd); ///< Set raw filehandle
196 /** \brief Adapt FileHandle to senf::Scheduler
197 \related senf::FileHandle
201 This function will be called by the Scheduler to retrieve the file descriptor of the
204 int retrieve_filehandle(FileHandle handle);
210 ///////////////////////////////hh.e////////////////////////////////////////
211 #include "FileHandle.cci"
212 //#include "FileHandle.ct"
213 //#include "FileHandle.cti"
220 // c-file-style: "senf"
221 // indent-tabs-mode: nil
222 // ispell-local-dictionary: "american"