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 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 copy constructor
93 // default copy assignment
96 // conversion constructors
98 template <class OtherPolicy>
99 SocketHandle(SocketHandle<OtherPolicy> other,
100 typename IsCompatible<OtherPolicy>::type * = 0);
101 ///< Convert from other socket handle checking policy
105 ///////////////////////////////////////////////////////////////////////////
107 template <class OtherPolicy>
108 typename IsCompatible<OtherPolicy>::type const & operator=(SocketHandle<OtherPolicy> other);
109 ///< Assign from other socket handle checking policy
112 void state(SocketStateMap & map, unsigned lod=0);
113 ///< Inquire state information of socket handle
114 /**< The map argument (a string to string mapping) will be
115 filled with information covering the current state of
116 the socket. The information provided depends on the
117 socket protocol. The amount of information returned can
118 be controlled using the \p lod value.
120 See senf::SocketProtocol::state() for more information,
121 how the Information is generated.
123 \param map string to string mapping to be filled with
125 \param lod level of detail requested. The interpretation
126 of this value is protocol specific
128 \implementation This member will be re-implemented in
129 every derived class. This is very important since
130 state() is \e not a virtual function (which we
131 don't want since we don't want to add a vtable
132 pointer to every handle instance). */
133 std::string dumpState(unsigned lod=0);
134 ///< Format complete state information as string
135 /**< Formats the complete state map value and returns it as
136 a single multi-line string.
138 \implementation This member will be re-implemented in
139 every derived class. See the state()
143 explicit SocketHandle(std::auto_ptr<SocketProtocol> protocol, bool isServer);
144 ///< Initialize SocketHandle providing the protocol
145 /**< \param protocol Protocol class of the protocol
146 implemented by this socket handle
147 \param isServer \c true, if this SobcketHandle instance
148 implements a server handle, \c false otherwise */
149 SocketHandle(FileHandle other, bool isChecked);
150 ///< Initialize SocketHandle from arbitrary checked
152 /**< This constructor is used to support up- and downcasting
153 of SocketHandle instances.
155 \warning It is absolutely necessary to ensure, that the
156 FileHandle passed in is \e really a SocketHandle
157 holding a SocketBody (and not a simple FileBody)
158 instance. Additionally. the SocketPolicy absolutely
161 \param other FileHandle to assign
162 \param isChecked has to be \c true
164 \todo Answer, why the heck I need the \c isChecked
168 SocketBody & body(); ///< Access socket body
169 /**< This member replaces the corresponding FileHandle
170 member and returns an appropriately cast body
172 SocketBody const & body() const; ///< Access socket body in const context
173 /**< This member replaces the corresponding FileHandle
174 member and returns an appropriately cast body
176 SocketProtocol const & protocol() const;
177 ///< Access protocol class
179 void assign(FileHandle other); /**< \internal */
182 static SocketHandle cast_static(FileHandle handle);
184 static SocketHandle cast_dynamic(FileHandle handle);
191 /** \brief Write stream status dump to output stream
193 Write senf::SocketHandle::dumpState() to \c os
195 \related senf::SocketHandle
197 template <class Policy>
198 std::ostream & operator<<(std::ostream & os, SocketHandle<Policy> handle);
200 /** \brief static socket (down-)cast
202 This function is like \c static_cast but for socket handles. It allows to downcast any
203 FileHandle to any SocketHandle (and its derived types). static_socket_cast will \e not check
204 the validity of the cast, it will assume, that the cast is valid.
206 The function will however check, that the cast is possible. Casting between (at compile
207 time) known incompatible types (like casting a SocketHandle with a communication policy of
208 ConnectedCommunicationPolicy to a SocketHandle with UnconnectedCommunicationPolicy will fail
212 If the type you cast to is not really a compatible socket handle type you will get undefined
213 behavior, probably your program will crash (You will get an assertion in debug builds).
215 \related senf::SocketHandle
217 template <class Target, class Source>
218 Target static_socket_cast(Source handle);
220 /** \brief dynamic socket (down-)cast
222 This function is like \c dynamic_cast but for socket handles. It is a runtime typechecked
223 version of static_socket_cast.
225 \throws std::bad_cast You have tried to perform an invalid down- or crosscast.
227 \related senf::SocketHandle
229 template <class Target, class Source>
230 Target dynamic_socket_cast(Source handle);
232 /** \brief dynamically check cast validity
234 This function will check, whether the given cast is valid. This is the same as checking, that
235 dynamic_socket_cast does not throw.
237 This member is needed, since there is no 'null' SocketHandle (comparable to a null pointer)
238 which could be returned by a non-throwing variant of dynamic_socket_cast.
240 \related senf::SocketHandle
242 template <class Target, class Source>
243 bool check_socket_cast(Source handle);
248 ///////////////////////////////hh.e////////////////////////////////////////
249 #include "SocketHandle.cci"
250 #include "SocketHandle.ct"
251 #include "SocketHandle.cti"
258 // c-file-style: "senf"
259 // indent-tabs-mode: nil
260 // ispell-local-dictionary: "american"