X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FSocketProtocol.hh;h=50301f94d983d8e865b0f543032f169297df3a95;hb=6f50bf49e282c0528f51faa0a245bbfa2b867399;hp=c829647441f050e79bf9fd7a69c4376b30e296b1;hpb=344c0f9eb4ea24e789e4dbb5e1d55006d288c2b1;p=senf.git diff --git a/Socket/SocketProtocol.hh b/Socket/SocketProtocol.hh index c829647..50301f9 100644 --- a/Socket/SocketProtocol.hh +++ b/Socket/SocketProtocol.hh @@ -1,9 +1,9 @@ // $Id$ // // Copyright (C) 2006 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) -// Stefan Bund +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY +// Stefan Bund // // This program is free software; you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by @@ -39,17 +39,17 @@ \htmlonly - SocketPolicy - ConcreteSocketProtocol - SocketProtocol - BSDSocketProtocol - AddressableBSDSocketProtocol - IPv4Protocol - IPv6Protocol - TCPProtocol - TCPv4SocketProtocol - TCPv6SocketProtocol - PacketProtocol + SocketPolicy + ConcreteSocketProtocol + SocketProtocol + BSDSocketProtocol + AddressableBSDSocketProtocol + IPv4Protocol + IPv6Protocol + TCPProtocol + TCPv4SocketProtocol + TCPv6SocketProtocol + PacketProtocol Protocols \endhtmlonly @@ -65,9 +65,9 @@ protocols are implemented using a simple multiple-inheritance hierarchy as shown above. Since the protocol class is protocol specific (how intelligent ...), the protocol class also - defines the complete socket policy to be used with it's protocol. Complete meaning, that every - policy axis must be assigned it's the most specific (that is derived) policy class to be used - with the protocol. + defines the \e complete socket policy to be used with it's protocol. Complete meaning, that + every policy axis must be assigned it's the most specific (that is derived) policy class to be + used with the protocol and that no policy axis is allowed to be left unspecified. \see \ref handle_group \n @@ -126,7 +126,8 @@ namespace senf { \attention SocketProtocol must \e always be inherited using public \e virtual inheritance. */ - class SocketProtocol : boost::noncopyable + class SocketProtocol + : boost::noncopyable { public: /////////////////////////////////////////////////////////////////////////// @@ -146,33 +147,30 @@ namespace senf { ///@} /////////////////////////////////////////////////////////////////////////// - SocketBody & body() const; ///< Access the socket body - /**< \todo we don't need body(), we should better provide a - handle() member which will return a simple FIleHandle - object (we cannot return some other derived class since - we don't know the Protocol or Policy at this point) */ virtual SocketPolicyBase const & policy() const = 0; - ///< Access the policy instance + ///< Access the policy instance /////////////////////////////////////////////////////////////////////////// // Virtual interface - virtual std::auto_ptr clone() const = 0; - ///< Polymorphically return a copy of this protocol class - /**< This member will create a new copy of the protocol - class on the heap. - \attention This member must be implemented in every \e - leaf protocol class to return a new instance of the - appropriate type. */ virtual unsigned available() const = 0; - ///< Return number of bytes available for reading without - ///< blocking + ///< Return (maximum) number of bytes available for reading + ///< without < blocking /**< This member will check in a (very, sigh) protocol - dependent way, how many bytes are guaranteed to be - readable from the socket without blocking even if the - socket is blocking. If the socket does not support - reading (viz. NotReadablePolicy is set), this member - should always return \c 0.*/ + dependent way, how many bytes may be read from a socket + in a single (non-blocking) read operation. If the + socket does not support reading (viz. NotReadablePolicy + is set), this member should always return \c 0. + + Depending on the protocol, it may not be possible to + return a good value. In this case, an upper bound may + be returned (e.g.: When reading from a socket which + returns ethernet frames, returning 1500 from + available() is ok). However, this should only be done + as a last resort. Also beware, that this number should + not be too large since the socket layer will always + need to allocate that number of bytes for the data to + be read. */ virtual bool eof() const = 0; ///< Check for end-of-file condition /**< This is another check which (like available()) is @@ -180,6 +178,20 @@ namespace senf { \c true only, if at end-of-file. If the protocol does not support the notion of EOF, this member should always return \c false. */ + + virtual void close() const; ///< Close socket + /**< This override will automatically \c shutdown() the + socket whenever it is closed. + \throws senf::SystemException */ + + virtual void terminate() const; ///< Forcibly close socket + /**< This override will automatically \c shutdown() 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 is therefore safe to be + called from a destructor. */ + virtual void state(SocketStateMap & map, unsigned lod) const; ///< Return socket state information /**< This member is called to add state information to the @@ -189,7 +201,7 @@ namespace senf { \a lod value with a default value of 0. The interpretation of the \a lod value is completely implementation defined. - + Every class derived from SocketProtocol should reimplement state(). The reimplemented method should call (all) baseclass-implementations of this @@ -200,34 +212,55 @@ namespace senf { keys are interpreted as hierarchical strings with '.' as a separator (like hostnames or struct or class members). They are automatically sorted correctly. - + The values are std:string with one additional feature: they allow assignment or conversion from *any* type as long as that type is streamable. This simplifies assigning non-string values to the map: - + \code - map["socket.protocol.ip.address"] = peer(); - map["socket.protocol.tcp.backlog"] = backlog(); + map["socket.protocol.ip.address"] << peer(); + map["socket.protocol.tcp.backlog"] << backlog(); \endcode - + This will work even if peer() returns an ip-address object or backlog() returns an integer. The values are automatically converted to their string representation. - - The operator "+=" also has been reimplemented to - simplify adding multiple values to a single entry: It - will automatically add a ", " separator if the string - is non-empty. */ + + Additionally, if the slot the date is written to is not + empty, the \<\< operator will add add a comma + as separator. */ protected: + FileHandle fh() const; ///< Get a FileHandle for this instance + /**< This member will re turn a FileHandle instance for this + protocol instance. You may cast this FileHandle + instance to a ClientSocketHandle / ServerSocketHandle + as long as you know some of the socket policy using + static_socket_cast or dynamic_socket_cast */ + + int fd() const; ///< Get file descriptor + /**< Returns the file descriptor this protocol instance + references. This is the same as fh().fd() but + is implemented here since it is needed so often. */ + + void fd(int) const; ///< Initialize file descriptor + /**< Assigns the file descriptor to the file handle, this + protocol instance references. Only valid, if the file + handle has not yet been assigned any descriptor (To + change the file descriptor association later, use \c + ::dup2()). */ private: - // backpointer to owning SocketBody instance - SocketBody * body_; - friend class SocketBody; - }; + virtual std::auto_ptr clone(bool isServer) const = 0; + virtual std::auto_ptr clone(int fd, bool isServer) const = 0; + virtual SocketBody & body() const = 0; + friend class SocketBody; + }; + + template class ClientSocketHandle; + template class ServerSocketHandle; /** \brief Concrete Socket Protocol implementation base class @@ -246,7 +279,7 @@ namespace senf { \doc init_client init_server */ - template + template class ConcreteSocketProtocol : public virtual SocketProtocol { @@ -270,12 +303,23 @@ namespace senf { /////////////////////////////////////////////////////////////////////////// Policy const & policy() const; - + protected: + ClientSocketHandle clientHandle() const; + ///< Get client handle for associated socket + /**< Returns a client handle for the socket associated with + this protocol instance */ + ServerSocketHandle serverHandle() const; + ///< Get server handle for associated socket + /**< Returns a server handle for the socket associated with + this protocol instance */ private: - Policy policy_; + virtual std::auto_ptr clone(bool isServer) const; + virtual std::auto_ptr clone(int fd, bool isServer) const; + virtual SocketBody & body() const; + Policy policy_; }; /// @}