From: g0dil Date: Fri, 12 Jan 2007 16:13:48 +0000 (+0000) Subject: Finisched SocketLibrary overview documentation X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=c34f597ae2a4ca654465fd7d81d3ce9d5ea4256f;p=senf.git Finisched SocketLibrary overview documentation git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@175 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox index 15993a6..30e9f07 100644 --- a/Socket/Mainpage.dox +++ b/Socket/Mainpage.dox @@ -124,22 +124,123 @@ it. Two SocketHandle instances can be converted into each other, as long as the SocketPolicies are compatible. - \section policy_interface The policy interface + \section protocol_interface The protocol interface + + \image html Protocols.png The socket handle classes and templates only implement the most - important socket API methods. To access the complete API, the - protocol interface is provided. Access to the protocol interface - is only possible via senf::ProtocolClientSocketHandle and + important socket API methods using the policy framework. To access + the complete API, the protocol interface is provided. Access to + the protocol interface is only possible via + senf::ProtocolClientSocketHandle and senf::ProtocolServerSocketHandle which have the necessary \c protocol() member. This member returns a reference to the protocol class instance which contains members covering all the API - function snot found in the SocketHandle interface. The protocol - interface is specific to the protocol. It's implementation is - quite free. Every protocol class will define the complete and - specific socket policy of it's socket handle. + function (mostly setsockopt/getsockopt related calls) not found in + the SocketHandle interface. The protocol interface is specific to + the protocol. It's implementation is quite free. The standard + 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. + */ /** \page extend Extending the Library + + There are two layers, on which the socket library can be + extended: On the protocol layer and on the policy layer. Extending + the protocol layer is quite simple and works as long as the + desired protocol does use the same BSD API used by the standard + internet protocols as implemented in the standard policies + (i.e. it uses ordinere read() and write() or rcvfrom() or sendto() + calls and so on). + + If however the implementation of a policy feature needs to be + changed, a new policy class has to be written. This also is not + very complicated however the integration is more complex. + + \section extend_protocol Writing a new protocol class + + Most protocols can be implemented by just implementing a new + protocol class. The protocol class must be derived from + senf::ConcreteSocketProtocol and takes the socket policy (as + created by senf::MakeSocketPolicy) as a template argument. See the + documentation of this class for the interface. + + \attention + You may want to use multiple inheritance as it is used in the + implementation of the standard protocols (See \ref + protocol_interface). You must however be extra careful to ensure, + that every class ultimately has senf::SocketPolicy as a public + \e virtual base. + + After the protocol class has been defined, you will probably want to + provide typedefs for the new protocol sockets. If the new protocol + is connection oriented, this will be like + + typedef senf::ProtocolClientSocketHandle MyProtocolClientSocketHandle; + typedef senf::ProtocolServerSocketHandle MyProtocolServerSocketHandle; + + + \section extend_policy Extending the policy framework + + If you have to extend the policy framework, you will need to be + aware of some important limitations of the socket library: + + \li When you define a new policy for some axis, this new policy + must not be derived from one of the existing concrete + policy classes (except of course the respective policy axis + base class). This is important since the policy type is \e not + polymorphic. The policy to be used is selected by the compiler + using the \e static type, which is exactly what is desired, + since this allows calls to be efficiently inlined. + + \li Therefore, extending the policy framework will make the new + socket probably \e incompatible with generic code which relies + on the policy axis which is extended. Example: If you write a + new write policy because your protocol does not use ordinary + write() system calls but some protocol specific API, Then any + generic function relying on senf::WritablePolicy will \e not + work with the new socket, since the socket does \e not have + this policy, it has some other kind of write policy. + + Therefore you need to be careful of what you are doing. The first + step is to find out, which policy you will have to implement. For + this, find the senf::ClientSocketHandle and/or + senf::ServerSocketHandle members you want to change. The following + table shows, which policy axis is responsible for which + members. The policy axis base class documentation contains further + information on how to implement that policy. + + + + + + + + + + + + + + + + + + +
SocketHandle memberPolicy member
senf::ClientSocketHandle::read ReadPolicy::read (\ref senf::ReadPolicyBase)
senf::ClientSocketHandle::readfrom ReadPolicy::readfrom (\ref senf::ReadPolicyBase)
senf::ClientSocketHandle::write WritePolicy::write (\ref senf::WritePolicyBase)
senf::ClientSocketHandle::writeto WritePolicy::writeto (\ref senf::WritePolicyBase)
senf::ClientSocketHandle::connect AddressingPolicy::connect (\ref senf::AddressingPolicyBase)
senf::ClientSocketHandle::bind AddressingPolicy::bind (\ref senf::AddressingPolicyBase)
senf::ClientSocketHandle::peer AddressingPolicy::peer (\ref senf::AddressingPolicyBase)
senf::ClientSocketHandle::local AddressingPolicy::local (\ref senf::AddressingPolicyBase)
senf::ClientSocketHandle::rcvbuf BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)
senf::ClientSocketHandle::sndbuf BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)
senf::ServerSocketHandle::bind AddressingPolicy::bind (\ref senf::AddressingPolicyBase)
senf::ServerSocketHandle::listen CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase)
senf::ServerSocketHandle::local AddressingPolicy::local (\ref senf::AddressingPolicyBase)
senf::ServerSocketHandle::accept CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)
senf::ServerSocketHandle::acceptfrom CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)
+ + As you can see from this list, not all policy axis directly + contribute to the SocketHandle interface. However, some policy + members additionally depend on other policy axis (example: + AddressingPolicy::connect is only defined if the communication + policy is ConnectedCommunication). */ /** \page implementation Implementation notes diff --git a/Socket/Protocols.dia b/Socket/Protocols.dia new file mode 100644 index 0000000..481d593 Binary files /dev/null and b/Socket/Protocols.dia differ diff --git a/Socket/SConscript b/Socket/SConscript index 9aff674..5baedce 100644 --- a/Socket/SConscript +++ b/Socket/SConscript @@ -18,4 +18,5 @@ SENFSCons.Doxygen(env, extra_sources = [ env.Dia2Png('SocketLibrary-classes.dia'), env.Dia2Png('FhHierarchy.dia'), env.Dia2Png('SocketPolicy.dia'), + env.Dia2Png('Protocols.dia'), ]) diff --git a/Socket/SocketLibrary-classes.dia b/Socket/SocketLibrary-classes.dia index f31dd1d..332b163 100644 Binary files a/Socket/SocketLibrary-classes.dia and b/Socket/SocketLibrary-classes.dia differ