Socket/Mainpage.dox

   1 /** \mainpage The SENF Socket Library
   2
   3     The Socket library provides a high level and object oriented
   4     abstraction of the BSD socket API. The abstraction is based on
   5     several concepts:
   6
   7     \li The basic visible interface is a \link handle_group handle
   8         object \endlink
   9     \li The socket interface relies on a \link policy_group policy
  10         framework \endlink to configure it's functionality
  11     \li The rest of the socket API is accessible using a classic
  12         inheritance hierarchy of \link protocol_group protocol classes
  13         \endlink
  14
  15     The handle/body architecture provides automatic reference counted
  16     management of socket instances, the policy framework provides
  17     highly efficient access to the most important socket functions
  18     (like reading and writing) and the inheritance hierarchy provides
  19     convenient access to the multitude of special and protocol
  20     dependent options.
  21
  22     \see \ref usage \n
  23          \ref handle_group \n
  24          \ref policy_group \n
  25          \ref protocol_group \n
  26          \ref extend \n
  27          \ref implementation
  28  */
  29
  30 /** \page usage Using the Socket Library
  31
  32     Whenever you use the socket library, what you will be dealing with
  33     are senf::FileHandle derived instances. The socket library relies
  34     on reference counting to automatically manage the underlying
  35     socket representation. This frees you of having to manage the
  36     socket lifetime explicitly.
  37
  38     \section usage_create Creating a Socket Handle
  39
  40     To create a new socket handle (opening a socket), you will need to
  41     use senf::ProtocolClientSocketHandle or
  42     senf::ProtocolServerSocketHandle. You will probably not use these
  43     templates as is but use proper typedefs (for example
  44     senf::TCPv4ClientSocketHandle or senf::PacketSocketHandle). The
  45     documentation for these socket handles are found in the protocol
  46     class (for example senf::TCPv4SocketProtocol or
  47     senf::PacketProtocol).
  48
  49     \section usage_reusable Writing Reusable Components
  50
  51     To make your code more flexible, you should not pass around your
  52     socket in this form. Most of your code will be using only a small
  53     subset of the senf::ProtocolClientSocketHandle or
  54     senf::ProtocolServerSocketHandle API. If instead of using the
  55     fully specified handle type you use a more incomplete type, you
  56     allow your code to be used with all socket which fulfill the
  57     minimal requirements of your code.
  58
  59     This works, by defining a special reduced policy or handle for
  60     your code:
  61
  62     \code
  63       typedef senf::ClientSocketHandle<
  64           senf::MakeSocketPolicy<
  65               senf::ReadablePolicy,
  66               senf::StreamFramingPolicy,
  67               senf::ConnectedCommunicationPolicy > > MyReadableHandle;
  68
  69     \endcode
  70
  71     This defines \c MyReadableHandle as a senf::ClientSocketHandle
  72     which will have only read functionality. Your code expects a
  73     stream interface (in contrast to a packet or datagram based
  74     interface). You will not have \c write or \c readfrom members. \c
  75     write will be disabled since the WritePolicy is unknown, \c
  76     readfrom will be disabled since a socket with the
  77     senf::ConnectedCommunicationPolicy does not have a \c readfrom
  78     member.
  79  */
  80
  81
  82
  83 /** \page extend Extending the Library
  84
  85     There are two layers, on which the socket library can be
  86     extended: On the protocol layer and on the policy layer. Extending
  87     the protocol layer is quite simple and works as long as the
  88     desired protocol does use the same BSD API used by the standard
  89     internet protocols as implemented in the standard policies
  90     (i.e. it uses ordinary read() and write() or rcvfrom() or sendto()
  91     calls and so on).
  92
  93     If however the implementation of a policy feature needs to be
  94     changed, a new policy class has to be written. This also is not
  95     very complicated however the integration is more complex.
  96
  97     \section extend_protocol Writing a new protocol class
  98
  99     Most protocols can be implemented by just implementing a new
 100     protocol class. The protocol class must be derived from
 101     senf::ConcreteSocketProtocol and takes the socket policy (as
 102     created by senf::MakeSocketPolicy) as a template argument. See the
 103     documentation of this class for the interface.
 104
 105     \attention
 106     You may want to use multiple inheritance as it is used in the
 107     implementation of the standard protocols (See \ref
 108     protocol_interface). You must however be extra careful to ensure,
 109     that every class ultimately has senf::SocketPolicy as a public
 110     \e virtual base.
 111
 112     After the protocol class has been defined, you will probably want to
 113     provide typedefs for the new protocol sockets. If the new protocol
 114     is connection oriented, this will be like
 115     <code>
 116     typedef senf::ProtocolClientSocketHandle<MyProtocolClass> MyProtocolClientSocketHandle;
 117     typedef senf::ProtocolServerSocketHandle<MyProtocolClass> MyProtocolServerSocketHandle;
 118     </code>
 119
 120     \section extend_policy Extending the policy framework
 121
 122     If you have to extend the policy framework, you will need to be
 123     aware of some important limitations of the socket library:
 124
 125     \li When you define a new policy for some axis, this new policy
 126         <em>must not</em> be derived from one of the existing concrete
 127         policy classes (except of course the respective policy axis
 128         base class). This is important since the policy type is \e not
 129         polymorphic. The policy to be used is selected by the compiler
 130         using the \e static type, which is exactly what is desired,
 131         since this allows calls to be efficiently inlined.
 132
 133     \li Therefore, extending the policy framework will make the new
 134         socket probably \e incompatible with generic code which relies
 135         on the policy axis which is extended. Example: If you write a
 136         new write policy because your protocol does not use ordinary
 137         write() system calls but some protocol specific API, Then any
 138         generic function relying on senf::WritablePolicy will \e not
 139         work with the new socket, since the socket does \e not have
 140         this policy, it has some other kind of write policy.
 141
 142     Therefore you need to be careful of what you are doing. The first
 143     step is to find out, which policy you will have to implement. For
 144     this, find the senf::ClientSocketHandle and/or
 145     senf::ServerSocketHandle members you want to change (see \ref
 146     senf::ClientSocketHandle and \ref senf::ServerSocketHandle).  Not
 147     all policy axis directly contribute to the SocketHandle
 148     interface. However, some policy members additionally depend on
 149     other policy axis (example: AddressingPolicy::connect is only
 150     defined if the communication policy is
 151     ConnectedCommunication).
 152
 153     \see policy_group
 154  */
 155
 156 /** \page implementation Implementation notes
 157
 158     \image html SocketLibrary-classes.png
 159  */
 160
 161 \f
 162 // Local Variables:
 163 // mode: c++
 164 // mode: flyspell
 165 // mode: auto-fill
 166 // ispell-local-dictionary: "american"
 167 // End: