1 // $Id:SocketHandle.hh 218 2007-03-20 14:39:32Z tho $
4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.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 SocketHandle public header
27 #ifndef HH_SocketHandle_
28 #define HH_SocketHandle_ 1
31 #include <memory> // std::auto_ptr
32 #include "FileHandle.hh"
33 #include "SocketPolicy.hh"
35 //#include "SocketHandle.mpp"
36 #include "SocketHandle.ih"
37 ///////////////////////////////hh.p////////////////////////////////////////
38 #include "SocketHandle.ih"
42 /// \addtogroup handle_group
45 /** \brief basic SocketHandle supporting protocol and policy abstraction
47 The senf::SocketHandle class introduces the two abstraction layers of the socket
48 library. senf::SocketHandle does \e not provide socket functions it only provides the
49 infrastructure necessary to support both, the protocol and the policy interface.
51 senf::SocketHandle takes the socket policy as a template argument. senf::SocketHandle also
52 introduces the protocol class. However, the class has no public constructors (see the
53 derived classes senf::ProtocolClientSocketHandle and senf::ProtocolServerSocketHandle).
55 The most important functionality provided by senf::SocketHandle is the conversion
56 constructor. This allows to implicitly convert between compatible socket handle types as
57 specified by the socket policy. The conversion constructor is defined in such a way, that
58 only valid conversions are possible (see the implementation source for a more complete
61 \note This class is \e not meant to be used as a base-class outside the library
62 implementation; The protected interface is for internal use only.
64 \todo Create a SocketHandleBase class and move some non-Policy dependent code there
66 template <class SPolicy>
71 ///////////////////////////////////////////////////////////////////////////
74 typedef SPolicy Policy;
76 /** \brief Check policy compatibility
78 IsCompatible is a template meta-function which will check some other socket policy for
79 conversion compatibility. This check is used in the senf::SocketPolicy implementation to
80 restrict the conversion operator.
82 template <class OtherPolicy>
84 : public boost::enable_if< SocketPolicyIsBaseOf<Policy,OtherPolicy>, SocketHandle >
87 ///////////////////////////////////////////////////////////////////////////
88 ///\name Structors and default members
91 // default default constructor
92 // default copy constructor
93 // default copy assignment
99 // conversion constructors
101 template <class OtherPolicy>
102 SocketHandle(SocketHandle<OtherPolicy> other,
103 typename IsCompatible<OtherPolicy>::type * = 0);
104 ///< Convert from other socket handle checking policy
108 ///////////////////////////////////////////////////////////////////////////
110 template <class OtherPolicy>
111 typename IsCompatible<OtherPolicy>::type const & operator=(SocketHandle<OtherPolicy> other);
112 ///< Assign from other socket handle checking policy
115 void state(SocketStateMap & map, unsigned lod=0);
116 ///< Inquire state information of socket handle
117 /**< The map argument (a string to string mapping) will be
118 filled with information covering the current state of
119 the socket. The information provided depends on the
120 socket protocol. The amount of information returned can
121 be controlled using the \p lod value.
123 See senf::SocketProtocol::state() for more information,
124 how the Information is generated.
126 \param map string to string mapping to be filled with
128 \param lod level of detail requested. The
129 interpretation of this value is protocol specific
131 \implementation This member will be re-implemented in
132 every derived class. This is very important since
133 state() is \e not a virtual function (which we
134 don't want since we don't want to add a vtable
135 pointer to every handle instance). */
136 std::string dumpState(unsigned lod=0);
137 ///< Format complete state information as string
138 /**< Formats the complete state map value and returns it as
139 a single multi-line string.
141 \param lod level of detail requested. The
142 interpretation of this value is protocol specific
144 \implementation This member will be re-implemented in
145 every derived class. See the state()
149 explicit SocketHandle(std::auto_ptr<SocketBody> body);
150 ///< Initialize SocketHandle providing the protocol
151 /**< \param protocol Protocol class of the protocol
152 implemented by this socket handle
153 \param isServer \c true, if this SobcketHandle instance
154 implements a server handle, \c false otherwise */
155 SocketHandle(FileHandle other, bool isChecked);
156 ///< Initialize SocketHandle from arbitrary checked
158 /**< This constructor is used to support up- and downcasting
159 of SocketHandle instances.
161 \warning It is absolutely necessary to ensure, that the
162 FileHandle passed in is \e really a SocketHandle
163 holding a SocketBody (and not a simple FileBody)
164 instance. Additionally. the SocketPolicy absolutely
167 \param other FileHandle to assign
168 \param isChecked has to be \c true
170 \todo Answer, why the heck I need the \c isChecked
173 SocketBody & body(); ///< Access socket body
174 /**< This member replaces the corresponding FileHandle
175 member and returns an appropriately cast body
177 SocketBody const & body() const; ///< Access socket body in const context
178 /**< This member replaces the corresponding FileHandle
179 member and returns an appropriately cast body
181 SocketProtocol const & protocol() const;
182 ///< Access protocol class
184 void assign(FileHandle other); /**< \internal */
187 static SocketHandle cast_static(FileHandle handle);
189 static SocketHandle cast_dynamic(FileHandle handle);
196 /** \brief Write stream status dump to output stream
198 Write senf::SocketHandle::dumpState() to \c os
200 \related senf::SocketHandle
202 template <class SPolicy>
203 std::ostream & operator<<(std::ostream & os, SocketHandle<SPolicy> handle);
205 /** \brief static socket (down-)cast
207 This function is like \c static_cast but for socket handles. It allows to downcast any
208 FileHandle to any SocketHandle (and its derived types). static_socket_cast will \e not check
209 the validity of the cast, it will assume, that the cast is valid.
211 The function will however check, that the cast is possible. Casting between (at compile
212 time) known incompatible types (like casting a SocketHandle with a communication policy of
213 ConnectedCommunicationPolicy to a SocketHandle with UnconnectedCommunicationPolicy will fail
217 If the type you cast to is not really a compatible socket handle type you will get undefined
218 behavior, probably your program will crash (You will get an assertion in debug builds).
220 \related senf::SocketHandle
222 template <class Target, class Source>
223 Target static_socket_cast(Source handle);
225 /** \brief dynamic socket (down-)cast
227 This function is like \c dynamic_cast but for socket handles. It is a runtime typechecked
228 version of static_socket_cast.
230 \throws std::bad_cast You have tried to perform an invalid down- or crosscast.
232 \related senf::SocketHandle
234 template <class Target, class Source>
235 Target dynamic_socket_cast(Source handle);
237 /** \brief dynamically check cast validity
239 This function will check, whether the given cast is valid. This is the same as checking, that
240 dynamic_socket_cast does not throw.
242 This member is needed, since there is no 'null' SocketHandle (comparable to a null pointer)
243 which could be returned by a non-throwing variant of dynamic_socket_cast.
245 \related senf::SocketHandle
247 template <class Target, class Source>
248 bool check_socket_cast(Source handle);
253 ///////////////////////////////hh.e////////////////////////////////////////
254 #include "SocketHandle.cci"
255 #include "SocketHandle.ct"
256 #include "SocketHandle.cti"
263 // c-file-style: "senf"
264 // indent-tabs-mode: nil
265 // ispell-local-dictionary: "american"
266 // compile-command: "scons -u test"
267 // comment-column: 40