X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FSocketHandle.ih;fp=Socket%2FSocketHandle.ih;h=c72b54ddd8981b540fa8e882e1e8905161e64ca8;hb=70256cc93f59f5d2c9b3428775a181e5e225bfc5;hp=5ad2b99243d81c48eb505e7492a2422bba8066cd;hpb=f4e0d3d4a32cc0bfc37855ad7f2c1e829911d233;p=senf.git diff --git a/Socket/SocketHandle.ih b/Socket/SocketHandle.ih index 5ad2b99..c72b54d 100644 --- a/Socket/SocketHandle.ih +++ b/Socket/SocketHandle.ih @@ -20,6 +20,10 @@ // 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 @@ -38,65 +42,141 @@ namespace senf { 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 ConvertibleString(T const & other); - template - ConvertibleString & operator+= (ConvertibleString const & other); - }; - - struct StateMapOrdering - : public std::binary_function - { - 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 + 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 + { + 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 ptr; - - /////////////////////////////////////////////////////////////////////////// - ///\name Structors and default members - ///@{ - - explicit SocketBody(std::auto_ptr protocol, bool isServer); - SocketBody(std::auto_ptr 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 ptr; + + /////////////////////////////////////////////////////////////////////////// + ///\name Structors and default members + ///@{ + + SocketBody(std::auto_ptr 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 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 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 protocol_; + bool isServer_; }; } @@ -108,4 +188,5 @@ namespace senf { // Local Variables: // mode: c++ // c-file-style: "senf" +// fill-column: 100 // End: