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 SocketPolicy>
71 ///////////////////////////////////////////////////////////////////////////
74 typedef SocketPolicy 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<SocketPolicy,OtherPolicy>,
88 ///////////////////////////////////////////////////////////////////////////
89 ///\name Structors and default members
92 // default default constructor
93 // default copy constructor
94 // default copy assignment
100 // conversion constructors
102 template <class OtherPolicy>
103 SocketHandle(SocketHandle<OtherPolicy> other,
104 typename IsCompatible<OtherPolicy>::type * = 0);
105 ///< Convert from other socket handle checking policy
109 ///////////////////////////////////////////////////////////////////////////
111 template <class OtherPolicy>
112 typename IsCompatible<OtherPolicy>::type const & operator=(SocketHandle<OtherPolicy> other);
113 ///< Assign from other socket handle checking policy
116 void state(SocketStateMap & map, unsigned lod=0);
117 ///< Inquire state information of socket handle
118 /**< The map argument (a string to string mapping) will be
119 filled with information covering the current state of
120 the socket. The information provided depends on the
121 socket protocol. The amount of information returned can
122 be controlled using the \p lod value.
124 See senf::SocketProtocol::state() for more information,
125 how the Information is generated.
127 \param map string to string mapping to be filled with
129 \param lod level of detail requested. The
130 interpretation of this value is protocol specific
132 \implementation This member will be re-implemented in
133 every derived class. This is very important since
134 state() is \e not a virtual function (which we
135 don't want since we don't want to add a vtable
136 pointer to every handle instance). */
137 std::string dumpState(unsigned lod=0);
138 ///< Format complete state information as string
139 /**< Formats the complete state map value and returns it as
140 a single multi-line string.
142 \param lod level of detail requested. The
143 interpretation of this value is protocol specific
145 \implementation This member will be re-implemented in
146 every derived class. See the state()
150 explicit SocketHandle(std::auto_ptr<SocketProtocol> protocol, bool isServer);
151 ///< Initialize SocketHandle providing the protocol
152 /**< \param protocol Protocol class of the protocol
153 implemented by this socket handle
154 \param isServer \c true, if this SobcketHandle instance
155 implements a server handle, \c false otherwise */
156 SocketHandle(FileHandle other, bool isChecked);
157 ///< Initialize SocketHandle from arbitrary checked
159 /**< This constructor is used to support up- and downcasting
160 of SocketHandle instances.
162 \warning It is absolutely necessary to ensure, that the
163 FileHandle passed in is \e really a SocketHandle
164 holding a SocketBody (and not a simple FileBody)
165 instance. Additionally. the SocketPolicy absolutely
168 \param other FileHandle to assign
169 \param isChecked has to be \c true
171 \todo Answer, why the heck I need the \c isChecked
174 SocketBody & body(); ///< Access socket body
175 /**< This member replaces the corresponding FileHandle
176 member and returns an appropriately cast body
178 SocketBody const & body() const; ///< Access socket body in const context
179 /**< This member replaces the corresponding FileHandle
180 member and returns an appropriately cast body
182 SocketProtocol const & protocol() const;
183 ///< Access protocol class
185 void assign(FileHandle other); /**< \internal */
188 static SocketHandle cast_static(FileHandle handle);
190 static SocketHandle cast_dynamic(FileHandle handle);
197 /** \brief Write stream status dump to output stream
199 Write senf::SocketHandle::dumpState() to \c os
201 \related senf::SocketHandle
203 template <class Policy>
204 std::ostream & operator<<(std::ostream & os, SocketHandle<Policy> handle);
206 /** \brief static socket (down-)cast
208 This function is like \c static_cast but for socket handles. It allows to downcast any
209 FileHandle to any SocketHandle (and its derived types). static_socket_cast will \e not check
210 the validity of the cast, it will assume, that the cast is valid.
212 The function will however check, that the cast is possible. Casting between (at compile
213 time) known incompatible types (like casting a SocketHandle with a communication policy of
214 ConnectedCommunicationPolicy to a SocketHandle with UnconnectedCommunicationPolicy will fail
218 If the type you cast to is not really a compatible socket handle type you will get undefined
219 behavior, probably your program will crash (You will get an assertion in debug builds).
221 \related senf::SocketHandle
223 template <class Target, class Source>
224 Target static_socket_cast(Source handle);
226 /** \brief dynamic socket (down-)cast
228 This function is like \c dynamic_cast but for socket handles. It is a runtime typechecked
229 version of static_socket_cast.
231 \throws std::bad_cast You have tried to perform an invalid down- or crosscast.
233 \related senf::SocketHandle
235 template <class Target, class Source>
236 Target dynamic_socket_cast(Source handle);
238 /** \brief dynamically check cast validity
240 This function will check, whether the given cast is valid. This is the same as checking, that
241 dynamic_socket_cast does not throw.
243 This member is needed, since there is no 'null' SocketHandle (comparable to a null pointer)
244 which could be returned by a non-throwing variant of dynamic_socket_cast.
246 \related senf::SocketHandle
248 template <class Target, class Source>
249 bool check_socket_cast(Source handle);
254 ///////////////////////////////hh.e////////////////////////////////////////
255 #include "SocketHandle.cci"
256 #include "SocketHandle.ct"
257 #include "SocketHandle.cti"
264 // c-file-style: "senf"
265 // indent-tabs-mode: nil
266 // ispell-local-dictionary: "american"
267 // compile-command: "scons -u test"
268 // comment-column: 40