Cross-Platform C++

ot::net
class MulticastSocket

#include "ot/net/MulticastSocket.h"

ot::net::DatagramSocket ot::ManagedObject A socket used for sending and receiving IP multicast packets. A MulticastSocket is a (UDP) DatagramSocket with the additional capabilities required for sending and receiving multicast packets. This is reflected by the fact that MulticastSocket publicly inherits from DatagramSocket.

IP multicasting is an efficient model for sending large quantities of data over a network while minimizing the amount of bandwidth used. Multicasting is based on the concept of groups, where datagrams are sent to a multicast group and any number of clients can join one or more groups.

A multicast group is specified by a class D IP address and UDP port number. Class D IP addresses are in the range 224.0.0.0 to 239.255.255.255 inclusive (but 224.0.0.0 is reserved and may not be used).

When a datagram packet is sent to a multicast group, all subscribers to that group (IP address and port) receive the message if they are within the time-to-live range of the packet. The time-to-live range of a datagram packet is set when the packet is sent, and is used to limit the number of multicast routing points that the packet will traverse.

The actual work of the MulticastSocket is performed by an instance of the DatagramSocketImpl class (the implementation class is loaded with knowledge about multi-casting even though the DatagramSocket interface is not). Instances of DatagramSocketImpl are created using a factory class: DatagramSocketImplFactory. An application can change the factory that creates the DatagramSocket implementation by calling MulticastSocket::SetDatagramSocketImplFactory(). OpenTop provides a default factory that creates plain DatagramSocketImpl instances which are suitable for most purposes.

Since:
1.3



Constructor/Destructor Summary
MulticastSocket()
         Creates an unbound multicast socket.
MulticastSocket(int port)
         Creates a multicast socket and binds it to the specified port on the local machine.

Method Summary
 virtual RefPtr< InetAddress > getNetworkInterface() const
         Returns an InetAddress representing the local interface from which multicast packets will be sent.
 virtual int getTimeToLive() const
         Returns the time-to-live value for multicast packets sent using this multicast socket.
 virtual void joinGroup(const InetAddress* pMulticastAddr)
         Joins a multicast group.
 virtual void joinGroup(const InetAddress* pMulticastAddr, const InetAddress* pInf)
         Joins a multicast group.
 virtual void leaveGroup(const InetAddress* pMulticastAddr)
         Leaves a multicast group.
 virtual void leaveGroup(const InetAddress* pMulticastAddr, const InetAddress* pInf)
         Leaves a multicast group.
 virtual void setNetworkInterface(const InetAddress* pInf)
         Sets the local multicast network interface from which multicast packets will be sent.
 virtual void setTimeToLive(int ttl)
         Set the time-to-live (TTL) value for multicast packets sent using this multicast socket.

Methods inherited from class ot::net::DatagramSocket
bind, close, connect, createDatagramSocketImpl, disconnect, getBroadcast, getDatagramSocketImpl, GetDatagramSocketImplFactory, getInetAddress, getLocalAddress, getLocalPort, getPort, getReceiveBufferSize, getReuseAddress, getSendBufferSize, getSoTimeout, isBound, isClosed, isConnected, receive, send, setBroadcast, SetDatagramSocketImplFactory, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSoTimeout, toString

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

Constructor/Destructor Detail

MulticastSocket

 MulticastSocket()
Creates an unbound multicast socket. The registered DatagramSocket factory is used to create an instance of DatagramSocketImpl to perform the actual work for the multicast socket.

When the socket is created the SO_REUSEADDR socket option is enabled.

Exceptions:
SocketException - if an error occurs creating the socket.

MulticastSocket

 MulticastSocket(int port)
Creates a multicast socket and binds it to the specified port on the local machine. The registered DatagramSocket factory is used to create an instance of DatagramSocketImpl to perform the actual work for the DatagramSocket.

When the socket is created the SO_REUSEADDR socket option is enabled.

Parameters:
port - the local port number to bind to
Exceptions:
SocketException - if an error occurs creating or binding the socket.
IllegalArgumentException - if port is not in the valid range
See also:
connect()

Method Detail

getNetworkInterface

virtual RefPtr< InetAddressgetNetworkInterface() const
Returns an InetAddress representing the local interface from which multicast packets will be sent. This is the value associated with the IP_MULTICAST_IF socket option.

Returns:
an InetAddress representing the multicast network interface.
Exceptions:
SocketException - is an error occurs getting the interface.
See also:
setNetworkInterface() `

getTimeToLive

virtual int getTimeToLive() const
Returns the time-to-live value for multicast packets sent using this multicast socket. The IP_MULTICAST_TTL option is used.

See also:
setTimeToLive()

joinGroup

virtual void joinGroup(const InetAddress* pMulticastAddr)
Joins a multicast group.

Parameters:
pMulticastAddr - the IP address of the multicast group to join.
Exceptions:
NullPointerException - if pMulticastAddr is null.
SocketException - if an error occurs joining the multicast group.
See also:
setNetworkInterface()

joinGroup

virtual void joinGroup(const InetAddress* pMulticastAddr,
                       const InetAddress* pInf)
Joins a multicast group.

Parameters:
pMulticastAddr - the IP address of the multicast group to join.
pInf - the network interface on which to join or null to allow the system to select an interface
Exceptions:
NullPointerException - if pMulticastAddr is null.
SocketException - if an error occurs joining the multicast group.
See also:
setNetworkInterface()

leaveGroup

virtual void leaveGroup(const InetAddress* pMulticastAddr)
Leaves a multicast group. It is not necessary to leave a multicast group in order to terminate. OpenTop closes the socket when all references are released and at this time the operating system ensures that all memberships associated with the socket are dropped.

Parameters:
pMulticastAddr - the IP address of the multicast group to leave.
Exceptions:
NullPointerException - if pMulticastAddr is null.
SocketException - if an error occurs leaving the multicast group.
See also:
setNetworkInterface()

leaveGroup

virtual void leaveGroup(const InetAddress* pMulticastAddr,
                        const InetAddress* pInf)
Leaves a multicast group. It is not necessary to leave a multicast group in order to terminate. OpenTop closes the socket when all references are released and at this time the operating system ensures that all memberships associated with the socket are dropped.

Parameters:
pMulticastAddr - the IP address of the multicast group to leave.
pInf - the network interface from which to leave or null to allow the system to select an interface
Exceptions:
NullPointerException - if pMulticastAddr is null.
SocketException - if an error occurs leaving the multicast group.
See also:
setNetworkInterface()

setNetworkInterface

virtual void setNetworkInterface(const InetAddress* pInf)
Sets the local multicast network interface from which multicast packets will be sent. This sets the value of the IP_MULTICAST_IF socket option.

Parameters:
inf - an InetAddress representing the required network interface.
Exceptions:
NullPointerException - if pInf is null.
SocketException - if an error occurs while setting the IP_MULTICAST_IF option.
See also:
getNetworkInterface()

setTimeToLive

virtual void setTimeToLive(int ttl)
Set the time-to-live (TTL) value for multicast packets sent using this multicast socket. The TTL value for a multicast packet specifies how many "hops" between multicast routers the packet can make before it expires.

Parameters:
ttl - the time-to-live value.
Exceptions:
SocketException - if an error occurs setting the IP_MULTICAST_TTL option.


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements