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 senf::FileHandle public header
27 #ifndef HH_FileHandle_
28 #define HH_FileHandle_ 1
31 #include <memory> // std::auto_ptr
32 #include "Utils/SafeBool.hh"
34 //#include "FileHandle.mpp"
35 ///////////////////////////////hh.p////////////////////////////////////////
36 #include "FileHandle.ih"
41 /** \brief Basic file handle wrapper
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).
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
51 \attention You should mostly pass around senf::FileHandle objects by \e value und not by
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.
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
63 \section filehandle_new Writing senf::FileHandle derived classes
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
70 \todo Add public default constructor to allow declaration of (empty) senf::FileHandle
74 : public SafeBool<FileHandle>
77 ///////////////////////////////////////////////////////////////////////////
80 ///////////////////////////////////////////////////////////////////////////
81 ///\name Structors and default members
84 // protected default constructor
85 // default copy constructor
86 // default copy assignment
89 // no conversion constructors
92 ///////////////////////////////////////////////////////////////////////////
94 void close(); ///< Close filehandle
95 /**< \throws senf::SystemException */
96 void terminate(); ///< Close filehandle ignoring error conditions
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
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)
107 bool blocking() const; ///< Return current blocking state
108 void blocking(bool status); ///< Set blocking state
110 bool eof() const; ///< Check EOF condition
111 /**< Depending on the socket type, this might never return \p
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
119 bool valid() const; ///< Check filehandle validity
120 /**< Any operation besides valid() will fail on an invalid
123 bool boolean_test() const; ///< Short for valid() && ! eof()
124 /**< This is called when using a FileHandle instance in a boolen
127 See the performance comments for the eof() member */
129 int fd() const; ///< Return the raw FileHandle
131 static FileHandle cast_static(FileHandle handle); /**< \internal */
132 static FileHandle cast_dynamic(FileHandle handle); /**< \internal */
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. */
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
148 void fd(int fd); ///< Set raw filehandle
154 int retrieve_filehandle(FileHandle handle);
158 ///////////////////////////////hh.e////////////////////////////////////////
159 #include "FileHandle.cci"
160 //#include "FileHandle.ct"
161 //#include "FileHandle.cti"
167 // c-file-style: "senf"