// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief senf::SocketHandle internal header
+ */
+
#ifndef IH_SocketHandle_
#define IH_SocketHandle_ 1
namespace detail {
+ /** \brief String supporting automatic type conversion
+
+ The ConvertibleString class is used to simplify creating a text representation of
+ arbitrary values. ConvertibleString is an ordinary string with an additional constructor
+ which allows constructing the string from any arbitrary, streamable type.
+
+ \note It is generally not advisable to derive from the standard library container
+ classes. However, in this concrete case, the derivation is safe since only the
+ additional functionality is added. It is absolutely safe to convert the derived class
+ back to the base type.
+ */
class ConvertibleString : public std::string
{
public:
ConvertibleString();
- ConvertibleString(bool v);
+ ConvertibleString(bool v); ///< Bool conversion constructor
+ /**< The bool conversion is defined explicitly to use a
+ specialized representation (the strings 'true' and
+ 'false') */
template <class T>
ConvertibleString(T const & other);
- template <class T>
- ConvertibleString & operator+= (ConvertibleString const & other);
- };
-
- struct StateMapOrdering
- : public std::binary_function<std::string,std::string,bool>
- {
- bool operator()(std::string a1, std::string a2) const;
- };
-
+ ///< Conversion constructor
+ /**< This constructor will assign the string from any
+ arbitrary type. It will use boost::lexical_cast to
+ convert the argument to its string representation. */
+
+ template <class T>
+ ConvertibleString & operator+= (ConvertibleString const & other);
+ ///< Add additional values with separator
+ /**< This operator facilitates the representation of
+ multiple values in a single string. Each value is first
+ converted to a string (using the type conversion
+ machinery of C++ and the ConvertibleString conversion
+ constructors). It is then appended to the current string
+ with ', ' as a separator (if the current string is
+ non-empty). */
+ };
+
+ /** \brief Special ordering for the SocketStateMap
+ \internal
+
+ This special ordering will sort 'hierarchical' strings correctly. A hierarchical string
+ in this context is a string like a path- or hostname with '.' as the hierarchical
+ separator.
+ */
+ struct StateMapOrdering
+ : public std::binary_function<std::string,std::string,bool>
+ {
+ bool operator()(std::string const & a1, std::string const & a2) const;
+ };
+
}
typedef std::map< std::string, detail::ConvertibleString, detail::StateMapOrdering > SocketStateMap;
namespace detail {
- std::string dumpState(SocketStateMap const & map);
+ /** \brief Helper to convert SocketStateMap to multiline string representation
+ \internal
+ */
+ std::string dumpState(SocketStateMap const & map);
}
+ /** \brief senf::SocketHandle referenced body
+
+ \internal
+
+ senf::SocketBody is the extended (relatively to senf::FileBody) body of
+ senf::SocketHandle. Every SocketHandle must have a SocketBody as it's body (and not a simple
+ FileBody). The casting and conversion operators defined will ensure this if used
+ properly. If this invariant is violated, your Program will probably crash.
+ */
class SocketBody
- : public FileBody
+ : public FileBody
{
public:
- ///////////////////////////////////////////////////////////////////////////
- // Types
-
- typedef boost::intrusive_ptr<SocketBody> ptr;
-
- ///////////////////////////////////////////////////////////////////////////
- ///\name Structors and default members
- ///@{
-
- explicit SocketBody(std::auto_ptr<SocketProtocol> protocol, bool isServer);
- SocketBody(std::auto_ptr<SocketProtocol> protocol, bool isServer, int fd);
-
- // no copy
- // no conversion constructors
-
- ///@}
- ///////////////////////////////////////////////////////////////////////////
-
- SocketProtocol const & protocol() const;
- bool isServer();
-
- void state(SocketStateMap & map, unsigned lod);
+ ///////////////////////////////////////////////////////////////////////////
+ // Types
+
+ typedef boost::intrusive_ptr<SocketBody> ptr;
+
+ ///////////////////////////////////////////////////////////////////////////
+ ///\name Structors and default members
+ ///@{
+
+ SocketBody(std::auto_ptr<SocketProtocol> protocol, bool isServer);
+ /**<
+ \param protocol Protocol class implementing the desired
+ protocol
+ \param isServer \c true, if this socket is a server
+ socket, false otherwise */
+ SocketBody(std::auto_ptr<SocketProtocol> protocol, bool isServer, int fd);
+ /**<
+ \param protocol Protocol class implementing the desired
+ protocol
+ \param isServer \c true, if this socket is a server
+ socket, false otherwise
+ \param fd socket file descriptor */
+
+ // no copy
+ // no conversion constructors
+
+ ///@}
+ ///////////////////////////////////////////////////////////////////////////
+
+ SocketProtocol const & protocol() const;
+ ///< Access the protocol instance
+ bool isServer(); ///< Check socket type
+ /**< \return \c true, if this is a server socket, \c false
+ otherwise */
+
+ void state(SocketStateMap & map, unsigned lod);
+ /**< \todo Move state into a virtual body member (which is
+ ok, since SocketBody already has virtual members). This
+ makes in unnecessary to reimplement dumpState and state
+ in every SocketHandle derived class */
private:
- virtual void v_close();
- virtual void v_terminate();
- virtual bool v_eof() const;
-
- boost::scoped_ptr<SocketProtocol> protocol_;
- bool isServer_;
+ virtual void v_close(); ///< Close socket
+ /**< This override will automatically \c shutdown() the
+ socket whenever it is closed.
+ \throws senf::SystemException */
+ virtual void v_terminate(); ///< Forcibly close socket
+ /**< This override will automatically \c shutfown() the
+ socket whenever it is called. Additionally it will
+ disable SO_LINGER to ensure, that v_terminate will not
+ block. Like the overriden method, this member will ignore
+ failures and will never throw. It therefore safe to be
+ called from a destructor. */
+ virtual bool v_eof() const; ///< Check for eof condition
+ /**< Since the eof check for sockets is very protocol
+ dependent, this member will forward the call to
+ senf::SocketPolicy::eof() */
+
+ boost::scoped_ptr<SocketProtocol> protocol_;
+ bool isServer_;
};
}
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
projects / senf.git / blobdiff