senf/Socket/Protocols/INet/MulticastSocketProtocol.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 // All Rights Reserved.
  24 //
  25 // Contributor(s):
  26 //   Stefan Bund <g0dil@berlios.de>
  27
  28 /** \file
  29     \brief MulticastSocketProtocol public header */
  30
  31 #ifndef HH_SENF_Socket_Protocols_INet_MulticastSocketProtocol_
  32 #define HH_SENF_Socket_Protocols_INet_MulticastSocketProtocol_ 1
  33
  34 // Custom includes
  35 #include <senf/Socket/SocketProtocol.hh>
  36 #include "INet4Address.hh"
  37 #include "INet6Address.hh"
  38
  39 //#include "MulticastSocketProtocol.mpp"
  40 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  41
  42 namespace senf {
  43
  44     ///\addtogroup protocol_facets_group
  45     //\{
  46
  47     /** \brief Generic addressing type independent multicast protocol facet
  48
  49         \todo implement complete new multicast API from RFC3678 (as far as supported by linux)
  50         \bug mcLeaveSSMSource fails with EADDRNOTAVAIL
  51      */
  52     class MulticastSocketProtocol
  53         : public virtual SocketProtocol
  54     {
  55     public:
  56         void broadcastEnabled(bool v) const; ///< Enable broadcast send/receive
  57                                         /**< If this option is enabled, broadcast UDP messages will
  58                                              be received on the socket and the socket will be
  59                                              allowed to send out broadcast UDP messages
  60                                              \param[in] v \c true to enable broadcast send/receive,
  61                                                  \c false to disable */
  62
  63         bool broadcastEnabled() const;  ///< Get broadcast send/receive state
  64                                         /**< \returns Current state of the broadcastEnabled()
  65                                              option. */
  66
  67
  68         unsigned mcTTL() const;         ///< Return current multicast TTL
  69         void mcTTL(unsigned value) const; ///< Set multicast TTL
  70
  71         bool mcLoop() const;            ///< Return current multicast loopback state.
  72         void mcLoop(bool value) const;  ///< Set multicast loopback state
  73                                         /**< If set to false via \c mcLoop(value) multicast messages
  74                                              will not be looped back to local sockets. Default value
  75                                              is \c true. */
  76
  77         void mcIface(std::string const & iface = std::string()) const;
  78                                         ///< Set multicast send interface of the socket
  79                                         /**< \param[in] iface name of interface to send multicast
  80                                              data from
  81
  82                                              Under current linux versions this option is broken at
  83                                              best. Don't use. */
  84     };
  85
  86     /** \brief Multicast protocol facet for INet4 addressable multicast enabled sockets
  87      */
  88     class INet4MulticastSocketProtocol
  89         : public MulticastSocketProtocol
  90     {
  91     public:
  92         void mcAddMembership(INet4Address const & mcAddr) const;
  93                                         ///< Join multicast group on default interface
  94                                         /**< This member will add \a mcAddr to the list of multicast
  95                                              groups received. The group is joined on the default
  96                                              interface.
  97                                              \param[in] mcAddr address of group to join */
  98         void mcAddMembership(INet4Address const & mcAddr, INet4Address const & localAddr) const;
  99                                         ///< join multicast group on a specific interface
 100                                         /**< This member will add \a mcAddr to the list of multicast
 101                                              groups received. The group is joined on the interface
 102                                              with the given local address.
 103                                              \deprecated Use \link mcAddMembership(INet4Address const & mcAddr, std::string const & iface) const mcAddMembership( \a mcAddr , \a iface )\endlink
 104                                                  for compatibility with the IPv6 API.
 105                                              \param[in] mcAddr address of group to join
 106                                              \param[in] localAddr address of interface to join on */
 107         void mcAddMembership(INet4Address const & mcAddr, std::string const & iface) const;
 108                                         ///< join multicast group on a specific interface
 109                                         /**< This member will add \a mcAddr to the list of multicast
 110                                              groups received. The group is joined on the given
 111                                              interface.
 112                                              \param[in] mcAddr address of group to join
 113                                              \param[in] iface interface name */
 114
 115         void mcDropMembership(INet4Address const & mcAddr) const;
 116                                         ///< Leave multicast group
 117                                         /**< This member will remove \a mcAddr from the list of
 118                                              multicast groups received. The group is left from the
 119                                              default interface.
 120                                              \param[in] mcAddr address of group to leave */
 121         void mcDropMembership(INet4Address const & mcAddr, INet4Address const & localAddr)
 122             const;
 123                                         ///< leave multicast group on a specific interface
 124                                         /**< This member will remove \a mcAddr from the list of
 125                                              multicast groups received. The group is left from the
 126                                              interface with the given local address.
 127                                              \deprecated Use \link mcDropMembership(INet4Address const & mcAddr, std::string const & iface) const mcDropMembership( \a mcAddr , \a iface )\endlink
 128                                                  for compatibility with the IPv6 API.
 129                                              \param[in] mcAddr address of group to leave
 130                                              \param[in] localAddr address of interface to leave
 131                                                  from */
 132         void mcDropMembership(INet4Address const & mcAddr, std::string const & iface)
 133             const;
 134                                         ///< leave multicast group on a specific interface
 135                                         /**< This member will remove \a mcAddr from the list of
 136                                              multicast groups received. The group is left from the
 137                                              interface with the given local address.
 138                                              \param[in] mcAddr address of group to leave
 139                                              \param[in] iface interface name */
 140
 141         void mcJoinSSMSource(INet4Address const & group, INet4Address const & source,
 142                              std::string const & iface) const;
 143                                         ///< join SSM multicast group
 144                                         /**< This call will join the multicast group \a group for
 145                                              traffic from \a source. A single group may be joined
 146                                              multiple times on different sources.
 147                                              \param[in] group multicast group to join
 148                                              \param[in] source SSM multicast source to join the
 149                                                  group on
 150                                              \param[in] iface interface to join the group on */
 151         void mcLeaveSSMSource(INet4Address const & group, INet4Address const & source,
 152                               std::string const & iface) const;
 153                                         ///< leave SSM multicast group
 154                                         /**< This call will leave the multicast group \a group for
 155                                              traffic from \a source.
 156                                              \param[in] group multicast group to leave
 157                                              \param[in] source SSM multicast source to leave the
 158                                                  group from
 159                                              \param[in] iface interface to leave the group on */
 160     };
 161
 162     /** \brief Multicast protocol facet for INet6 addressable multicast enabled sockets
 163
 164         This implementation supports INet6 mapped INet4 multicast addresses. This is a linux
 165         specific extension and NOT part of the relevant RFCs.
 166      */
 167     class INet6MulticastSocketProtocol
 168         : public MulticastSocketProtocol
 169     {
 170     public:
 171         void mcAddMembership(INet6Address const & mcAddr) const;
 172                                         ///< Join multicast group on default interface
 173                                         /**< This member will add \a mcAddr to the list of multicast
 174                                              groups received. The group is joined on the default
 175                                              interface.
 176                                              \param[in] mcAddr address of group to join */
 177         void mcAddMembership(INet6Address const & mcAddr, std::string const & iface) const;
 178                                         ///< join multicast group on a specific interface
 179                                         /**< This member will add \a mcAddr to the list of multicast
 180                                              groups received. The group is joined on the given
 181                                              interface.
 182                                              \param[in] mcAddr address of group to join
 183                                              \param[in] iface interface name */
 184
 185         void mcDropMembership(INet6Address const & mcAddr) const;
 186                                         ///< Leave multicast group
 187                                         /**< This member will remove \a mcAddr from the list of
 188                                              multicast groups received. The group is left from the
 189                                              default interface.
 190                                              \param[in] mcAddr address of group to leave */
 191         void mcDropMembership(INet6Address const & mcAddr, std::string const & iface) const;
 192                                         ///< leave multicast group on a specific interface
 193                                         /**< This member will remove \a mcAddr from the list of
 194                                              multicast groups received. The group is left from the
 195                                              interface with the given local address.
 196                                              \param[in] mcAddr address of group to leave
 197                                              \param[in] iface interface name */
 198
 199         void mcJoinSSMSource(INet6Address const & group, INet6Address const & source,
 200                              std::string const & iface) const;
 201                                         ///< join SSM multicast group
 202                                         /**< This call will join the multicast group \a group for
 203                                              traffic from \a source. A single group may be joined
 204                                              multiple times on different sources.
 205                                              \param[in] group multicast group to join
 206                                              \param[in] source SSM multicast source to join the
 207                                                  group on
 208                                              \param[in] iface interface to join the group on. If set
 209                                                  to the empty string, use the default interface. */
 210         void mcJoinSSMSource(INet6Address const & group, INet6Address const & source,
 211                              int ifacei = 0) const;
 212                                         ///< join SSM multicast group
 213                                         /**< This call will join the multicast group \a group for
 214                                              traffic from \a source. A single group may be joined
 215                                              multiple times on different sources.
 216                                              \param[in] group multicast group to join
 217                                              \param[in] source SSM multicast source to join the
 218                                                  group on
 219                                              \param[in] ifacei optional interface index to join the
 220                                                  group on */
 221         void mcLeaveSSMSource(INet6Address const & group, INet6Address const & source,
 222                               std::string const & iface) const;
 223                                         ///< leave SSM multicast group
 224                                         /**< This call will leave the multicast group \a group for
 225                                              traffic from \a source.
 226                                              \param[in] group multicast group to leave
 227                                              \param[in] source SSM multicast source to leave the
 228                                                  group from
 229                                              \param[in] iface interface to leave the group on */
 230     };
 231
 232     //\}
 233 }
 234
 235 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 236 //#include "MulticastSocketProtocol.cci"
 237 //#include "MulticastSocketProtocol.ct"
 238 //#include "MulticastSocketProtocol.cti"
 239 #endif
 240
 241 \f
 242 // Local Variables:
 243 // mode: c++
 244 // fill-column: 100
 245 // comment-column: 40
 246 // c-file-style: "senf"
 247 // indent-tabs-mode: nil
 248 // ispell-local-dictionary: "american"
 249 // compile-command: "scons -u test"
 250 // End: