MulticastSocket Class Reference

A UDP multicast socket. More...

#include <MulticastSocket.h++>

Inheritance diagram for MulticastSocket:

Collaboration diagram for MulticastSocket:

Public Member Functions
	MulticastSocket (uint16_t port=0)
	Construct a new MulticastSocket bound to the given port. More...
	~MulticastSocket ()
	Destructor. More...
void	join (const String &address)
	Join a multicast group. More...
void	join (const InetAddress &address)
	Join a multicast group. More...
void	join (const String &address, const NetworkInterface &ixface)
	Join a multicast group on a specific interface. More...
void	join (const InetAddress &address, const NetworkInterface &ixface)
	Join a multicast group on a specific interface. More...
void	leave (const String &address)
	Leave a multicast group. More...
void	leave (const InetAddress &address)
	Leave a multicast group. More...
void	leave (const String &address, const ccxx::NetworkInterface &ixface)
	Leave a multicast group on a specific interface. More...
void	leave (const InetAddress &address, const ccxx::NetworkInterface &ixface)
	Leave a multicast group on a specific interface. More...
void	setTTL (uint8_t ttl)
	Set the TTL (time-to-live) value for outgoing multicast datagrams. More...
uint8_t	getTTL () const
	Get the TTL value. More...
void	setLoopbackEnabled (bool enabled)
	Enable or disable local loopback of multicast datagrams. More...
bool	isLoopbackEnabled () const
	Determine if local loopback is enabled. More...
void	connect (const String &addr, uint16_t port)
	Connect the datagram socket to a remote endpoint. More...
void	connect (const SocketAddress &addr)
	Connect the datagram socket to a remote endpoint. More...
size_t	send (const byte_t *buffer, size_t buflen)
	Send a datagram to the remote endpoint. More...
size_t	send (ByteBuffer &buffer)
	Send a datagram to the remote endpoint. More...
size_t	send (const byte_t *buffer, size_t buflen, const SocketAddress &dest)
	Send a datagram to a given address. More...
size_t	send (ByteBuffer &buffer, const SocketAddress &dest)
	Send a datagram to a given address. More...
size_t	receive (byte_t *buffer, size_t buflen)
	Receive a datagram from the remote endpoint, and write it to a buffer. More...
size_t	receive (ByteBuffer &buffer)
	Receive a datagram from the remote endpoint, and write it to a buffer. More...
size_t	receive (byte_t *buffer, size_t buflen, SocketAddress &source)
	Receive a datagram and write it to a buffer. More...
size_t	receive (ByteBuffer &buffer, SocketAddress &source)
	Receive a datagram and write it to a buffer. More...
void	setBroadcast (bool flag)
	Enable or disable broadcast. More...
bool	getBroadcast () const
	Determine if broadcast is enabled. More...
virtual void	init ()
	Initialize the socket. More...
virtual void	shutdown ()
	Shut down the socket. More...
void	setTimeout (timespan_ms_t timeout)
	Set the timeout for the socket. More...
void	setReceiveBufSize (size_t size)
	Set the size of the socket's internal receive buffer. More...
size_t	getReceiveBufSize () const
	Get the size of the socket's internal receive buffer. More...
void	setSendBufSize (size_t size)
	Set the size of the socket's internal send buffer. More...
size_t	getSendBufSize () const
	Get the size of the socket's internal send buffer. More...
void	setLingerTime (timespan_s_t timeout)
	Set the linger time for the socket. More...
timespan_s_t	getLingerTime () const
	Get the linger time for the socket. More...
void	setReuseAddress (bool enable)
	Enable or disable the SO_REUSEADDR option on the socket. More...
bool	getReuseAddress () const
	Determine if the SO_REUSEADDR option is enabled or disabled. More...
void	setKeepAlive (bool enable)
	Enable or disable the SO_KEEPALIVE option on the socket. More...
bool	getKeepAlive ()
	Determine if the SO_KEEPALIVE option is enabled or disabled. More...
void	setTCPDelay (bool enable)
	Enable or disable the Nagle algorithm for send coalescing. More...
bool	getTCPDelay ()
	Determine if the Nagle algorithm is enabled or disabled. More...
bool	isInitialized () const
	Determine if the socket has been initialized. More...
bool	isConnected () const
	Determine if the socket is connected. More...
NetProtocol	getType () const
	Get the socket type. More...
const SocketAddress &	getLocalAddress () const
	Get the address of the local end of the socket. More...
const SocketAddress &	getRemoteAddress () const
	Get the address of the remote (peer) end of the socket. More...

Static Public Attributes
static uint8_t	TTL_HOST = 0
	A TTL value representing localhost scope. More...
static uint8_t	TTL_SUBNET = 1
	A TTL value representing subnet scope. More...
static uint8_t	TTL_SITE = 32
	A TTL value representing site-wide scope. More...
static uint8_t	TTL_REGION = 64
	A TTL value representing regional scope. More...
static uint8_t	TTL_CONTINENT = 128
	A TTL value representing continental scope. More...
static uint8_t	TTL_UNRESTRICTED = 255
	A TTL value representing unlimited scope. More...
static const size_t	MAX_DATAGRAM_SIZE = 16384
	The maximum size of a datagram packet. More...

Protected Types
enum	IOWaitMode { WaitWrite, WaitRead }

Protected Member Functions
SocketHandle	getSocketHandle () const
	Get the underlying socket handle for this socket. More...
void	waitForIO (IOWaitMode mode)
	Wait for the socket to become ready for reading or writing. More...

Protected Attributes
NetProtocol	_type
	The socket type. More...
SocketHandle	_socket
	A handle to the socket itself. More...
SocketAddress	_raddr
	The remote address. More...
SocketAddress	_laddr
	The local address. More...
int	_sotimeout
	The timeout value. More...

Detailed Description

A UDP multicast socket.

Multicast socket addresses range from 224.0.0.0 to 239.255.255.255, inclusive, with 224.0.0.0 reserved.

Author

Mark Lindner

Member Enumeration Documentation

IOWaitMode

enum IOWaitMode

protectedinherited

Enumerator
WaitWrite
WaitRead

Constructor & Destructor Documentation

MulticastSocket()

MulticastSocket

(

uint16_t

port = 0

)

Construct a new MulticastSocket bound to the given port.

Parameters

port	The port on which to listen.

~MulticastSocket()

~MulticastSocket

(

)

Destructor.

Member Function Documentation

connect() [1/2]

void connect ( const String &  addr, uint16_t  port  )

virtualinherited

Connect the datagram socket to a remote endpoint.

Connecting a datagram socket to an address does not actually establish a network connection, but rather restricts the socket so that it may only exchange datagrams with that address.

Parameters

addr	The address, which may either be a dot-separated IP address or a DNS name.
port	The port number.

Exceptions

IOException

If an error occurs.

Reimplemented from Socket.

connect() [2/2]

void connect ( const SocketAddress &  addr )

virtualinherited

Connect the datagram socket to a remote endpoint.

Connecting a datagram socket to an address does not actually establish a network connection, but rather restricts the socket so that it may only exchange datagrams with that address.

Parameters

addr	The address.

Exceptions

IOException

If an error occurs.

Reimplemented from Socket.

getBroadcast()

bool getBroadcast ( ) const

inherited

Determine if broadcast is enabled.

Returns

true if broadcast is enabled, false otherwise.

Exceptions

SocketException

If an error occurs.

getKeepAlive()

bool getKeepAlive ( )

inherited

Determine if the SO_KEEPALIVE option is enabled or disabled.

Returns

true if the option is enabled, false otherwise.

Exceptions

SocketException

If a socket error occurs.

getLingerTime()

timespan_s_t getLingerTime ( ) const

inherited

Get the linger time for the socket.

Returns

The linger time, in seconds, or -1 if the feature is disabled.

Exceptions

SocketException

If the linger time could not be retrieved.

getLocalAddress()

const SocketAddress& getLocalAddress ( ) const

inlineinherited

Get the address of the local end of the socket.

getReceiveBufSize()

size_t getReceiveBufSize ( ) const

inherited

Get the size of the socket's internal receive buffer.

Returns

The size, in bytes.

Exceptions

SocketException

If the size could not be changed.

getRemoteAddress()

const SocketAddress& getRemoteAddress ( ) const

inlineinherited

Get the address of the remote (peer) end of the socket.

getReuseAddress()

bool getReuseAddress ( ) const

inherited

Determine if the SO_REUSEADDR option is enabled or disabled.

Returns

true if the option is enabled, false otherwise.

Exceptions

SocketException

If a socket error occurs.

getSendBufSize()

size_t getSendBufSize ( ) const

inherited

Get the size of the socket's internal send buffer.

Returns

The size, in bytes.

Exceptions

SocketException

If the size could not be changed.

getSocketHandle()

SocketHandle getSocketHandle ( ) const

inlineprotectedinherited

Get the underlying socket handle for this socket.

getTCPDelay()

bool getTCPDelay ( )

inherited

Determine if the Nagle algorithm is enabled or disabled.

Returns

true if the Nagle algorithm is enabled (TCP_NODELAY off), false otherwise.

Exceptions

SocketException

If a socket error occurs.

getTTL()

uint8_t getTTL

(

)

const

Get the TTL value.

Exceptions

SocketException

If the operation fails.

getType()

NetProtocol getType ( ) const

inlineinherited

Get the socket type.

init()

void init ( )

virtualinherited

Initialize the socket.

This method creates the underlying socket object.

Exceptions

SocketException

If the socket could not be created.

Reimplemented in ServerSocket.

isConnected()

bool isConnected ( ) const

inlineinherited

Determine if the socket is connected.

isInitialized()

bool isInitialized ( ) const

inlineinherited

Determine if the socket has been initialized.

isLoopbackEnabled()

bool isLoopbackEnabled

(

)

const

Determine if local loopback is enabled.

Returns

true if loopback is enabled, false otherwise.

Exceptions

SocketException

If the operation fails.

join() [1/4]

void join

(

const String &

address

)

Join a multicast group.

Parameters

address

The address to join, as a dot-separated IP address.

Exceptions

SocketException

If the operation fails.

join() [2/4]

void join

(

const InetAddress &

address

)

Join a multicast group.

Parameters

address

The address to join.

Exceptions

SocketException

If the operation fails.

join() [3/4]

void join	(	const String &	address,
		const NetworkInterface &	ixface
	)

Join a multicast group on a specific interface.

Parameters

address	The address to join, as a dot-separated IP address.
ixface	The network interface.

Exceptions

SocketException

If the operation fails.

join() [4/4]

void join	(	const InetAddress &	address,
		const NetworkInterface &	ixface
	)

Join a multicast group on a specific interface.

Parameters

address	The address to join.
ixface	The network interface.

Exceptions

SocketException

If the operation fails.

leave() [1/4]

void leave

(

const String &

address

)

Leave a multicast group.

Parameters

address

The address to leave, as a dot-separated IP address.

Exceptions

SocketException

If the operation fails.

leave() [2/4]

void leave

(

const InetAddress &

address

)

Leave a multicast group.

Parameters

address

The address to leave.

Exceptions

SocketException

If the operation fails.

leave() [3/4]

void leave	(	const String &	address,
		const ccxx::NetworkInterface &	ixface
	)

Leave a multicast group on a specific interface.

Parameters

address	The address to leave, as a dot-separated IP address.
ixface	The network interface.

Exceptions

SocketException

If the operation fails.

leave() [4/4]

void leave	(	const InetAddress &	address,
		const ccxx::NetworkInterface &	ixface
	)

Leave a multicast group on a specific interface.

Parameters

address	The address to leave.
ixface	The network interface.

Exceptions

SocketException

If the operation fails.

receive() [1/4]

size_t receive ( byte_t *  buffer, size_t  buflen  )

inherited

Receive a datagram from the remote endpoint, and write it to a buffer.

The socket must be connected before this method can be used.

Parameters

buffer	The raw buffer to write the data to.
buflen	The length of the buffer.

Returns

The number of bytes received.

Exceptions

IOException

If an error occurs.

receive() [2/4]

size_t receive ( ByteBuffer &  buffer )

inherited

Receive a datagram from the remote endpoint, and write it to a buffer.

The socket must be connected before this method can be used.

Parameters

buffer

The buffer to write the data to.

Returns

The number of bytes received.

Exceptions

IOException

If an error occurs.

receive() [3/4]

size_t receive ( byte_t *  buffer, size_t  buflen, SocketAddress &  source  )

inherited

Receive a datagram and write it to a buffer.

Parameters

buffer	The raw buffer to write the data to.
buflen	The length of the buffer.
source	The object in which to place the source address of the received datagram.

Returns

The number of bytes received.

Exceptions

IOException

If an error occurs.

receive() [4/4]

size_t receive ( ByteBuffer &  buffer, SocketAddress &  source  )

inherited

Receive a datagram and write it to a buffer.

Parameters

buffer	The buffer to write the data to.
source	The object in which to place the source address of the received datagram.

Returns

The number of bytes received.

Exceptions

IOException

If an error occurs.

send() [1/4]

size_t send ( const byte_t *  buffer, size_t  buflen  )

inherited

Send a datagram to the remote endpoint.

The socket must be connected before this method can be used.

Parameters

buffer	The raw buffer containing the data to send.
buflen	The length of the buffer.

Returns

The number of bytes sent.

Exceptions

IOException

If an error occurs.

send() [2/4]

size_t send ( ByteBuffer &  buffer )

inherited

Send a datagram to the remote endpoint.

The socket must be connected before this method can be used.

Parameters

buffer

The buffer containing the data to send.

Returns

The number of bytes sent.

Exceptions

IOException

If an error occurs.

send() [3/4]

size_t send ( const byte_t *  buffer, size_t  buflen, const SocketAddress &  dest  )

inherited

Send a datagram to a given address.

Parameters

buffer	The raw buffer containing the data to send.
buflen	The length of the buffer.
dest	The destination address.

Returns

The number of bytes sent.

Exceptions

IOException

If an error occurs.

send() [4/4]

size_t send ( ByteBuffer &  buffer, const SocketAddress &  dest  )

inherited

Send a datagram to a given address.

Parameters

buffer	The buffer containing the data to send.
dest	The destination address.

Returns

The number of bytes sent.

Exceptions

IOException

If an error occurs.

setBroadcast()

void setBroadcast ( bool  flag )

inherited

Enable or disable broadcast.

When enabled, the socket will receive packets sent to a broadcast address and is allowed to send packets to a broadcast address.

Parameters

flag	A flag indicating whether the feature should be enabled or disabled.

Exceptions

SocketException

If an error occurs.

setKeepAlive()

void setKeepAlive ( bool  enable )

inherited

Enable or disable the SO_KEEPALIVE option on the socket.

Parameters

enable

true to enable the option false to disable it.

Exceptions

SocketException

If a socket error occurs.

setLingerTime()

void setLingerTime ( timespan_s_t  timeout )

inherited

Set the linger time for the socket.

Parameters

timeout

The new linger time, in seconds; a negative value disables the linger feature.

Exceptions

SocketException

If the linger time could not be changed.

setLoopbackEnabled()

void setLoopbackEnabled

(

bool

enabled

)

Enable or disable local loopback of multicast datagrams.

When the loopback is enabled, the sender receives copies of all multicast datagrams that it sends.

Parameters

enabled

true if loopback should be enabled, false if it should be disabled.

Exceptions

SocketException

If the operation fails.

setReceiveBufSize()

void setReceiveBufSize ( size_t  size )

inherited

Set the size of the socket's internal receive buffer.

Parameters

size	The new size, in bytes.

Exceptions

SocketException

If the size could not be changed.

setReuseAddress()

void setReuseAddress ( bool  enable )

inherited

Enable or disable the SO_REUSEADDR option on the socket.

This method may only be called before the socket has been initialized. This option is off by default in newly created sockets.

Parameters

enable

true to enable the option false to disable it.

Exceptions

SocketException

If a socket error occurs, or if the call was made after the socket was initialized.

setSendBufSize()

void setSendBufSize ( size_t  size )

inherited

Set the size of the socket's internal send buffer.

Parameters

size	The new size, in bytes.

Exceptions

SocketException

If the size could not be changed.

setTCPDelay()

void setTCPDelay ( bool  enable )

inherited

Enable or disable the Nagle algorithm for send coalescing.

Parameters

enable

true to enable the Nagle algorithm (TCP_NODELAY off), false to disable it (TCP_NODELAY on).

Exceptions

SocketException

If a socket error occurs.

setTimeout()

void setTimeout ( timespan_ms_t  timeout )

inherited

Set the timeout for the socket.

The timeout affects both I/O and connections.

Parameters

timeout

The timeout, in milliseconds.

Exceptions

SocketException

If an error occurs.

setTTL()

void setTTL

(

uint8_t

ttl

)

Set the TTL (time-to-live) value for outgoing multicast datagrams.

The TTL is the number of "hops" that a packet is allowed to make on the network before being discarded.

Parameters

ttl	The new TTL value.

Exceptions

SocketException

If the operation fails.

shutdown()

void shutdown ( )

virtualinherited

Shut down the socket.

Closes the connection and destroys the underlying socket object.

Reimplemented in StreamSocket, and ServerSocket.

waitForIO()

void waitForIO ( IOWaitMode  mode )

protectedinherited

Wait for the socket to become ready for reading or writing.

Parameters

mode	The wait mode; one of WaitWrite or WaitRead.

Exceptions

IOException

On timeout or other error.

Member Data Documentation

_laddr

SocketAddress _laddr

protectedinherited

The local address.

_raddr

SocketAddress _raddr

protectedinherited

The remote address.

_socket

SocketHandle _socket

protectedinherited

A handle to the socket itself.

_sotimeout

int _sotimeout

protectedinherited

The timeout value.

_type

NetProtocol _type

protectedinherited

The socket type.

MAX_DATAGRAM_SIZE

const size_t MAX_DATAGRAM_SIZE = 16384

staticinherited

The maximum size of a datagram packet.

TTL_CONTINENT

uint8_t TTL_CONTINENT = 128

static

A TTL value representing continental scope.

TTL_HOST

uint8_t TTL_HOST = 0

static

A TTL value representing localhost scope.

TTL_REGION

uint8_t TTL_REGION = 64

static

A TTL value representing regional scope.

TTL_SITE

uint8_t TTL_SITE = 32

static

A TTL value representing site-wide scope.

TTL_SUBNET

uint8_t TTL_SUBNET = 1

static

A TTL value representing subnet scope.

TTL_UNRESTRICTED

uint8_t TTL_UNRESTRICTED = 255

static

A TTL value representing unlimited scope.

---

The documentation for this class was generated from the following files:

• MulticastSocket.h++
• MulticastSocket.c++