---

ACE_SOCK_Dgram_Mcast Class Reference

Defines the ACE socket wrapper for UDP/IP multicast. More...

#include <SOCK_Dgram_Mcast.h>

Inheritance diagram for ACE_SOCK_Dgram_Mcast:

[legend]Collaboration diagram for ACE_SOCK_Dgram_Mcast:

[legend]List of all members.

Public Types
enum	options {   OPT_BINDADDR_NO = 0, OPT_BINDADDR_YES = 1, DEFOPT_BINDADDR = OPT_BINDADDR_NO, OPT_NULLIFACE_ONE = 0,   OPT_NULLIFACE_ALL = 2, DEFOPT_NULLIFACE = OPT_NULLIFACE_ALL, DEFOPTS = DEFOPT_BINDADDR | DEFOPT_NULLIFACE }
	Option parameters. More...
Public Methods
	ACE_SOCK_Dgram_Mcast (options opts=DEFOPTS)
	~ACE_SOCK_Dgram_Mcast (void)
int	open (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0, int reuse_addr=1)
int	subscribe (const ACE_INET_Addr &mcast_addr, int reuse_addr=1, const ACE_TCHAR *net_if=0, int protocol_family=PF_INET, int protocol=0)
int	join (const ACE_INET_Addr &mcast_addr, int reuse_addr=1, const ACE_TCHAR *net_if=0)
int	unsubscribe (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0, int protocol_family=PF_INET, int protocol=0)
int	leave (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0)
int	unsubscribe (void)
	Unsubscribe all current subscriptions.
ssize_t	send (const void *buf, size_t n, int flags=0) const
ssize_t	send (const iovec iov[], int n, int flags=0) const
int	set_option (int option, char optval)
	Set a socket option.
void	dump (void) const
	Dump the state of an object.
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
	Declare the dynamic allocation hooks.
Protected Methods
int	open_i (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0, int reuse_addr=1)
int	make_multicast_ifaddr (ip_mreq *mreq, const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if)
int	make_multicast_ifaddr_i (ip_mreq *mreq, const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=ACE_LIB_TEXT("le0"))
int	clear_subs_list (void)
	Empty the dynamic subscription list.
Private Methods
int	subscribe_ifs (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if, int reuse_addr)
int	subscribe_i (const ACE_INET_Addr &mcast_addr, int reuse_addr=1, const ACE_TCHAR *net_if=0)
	Do subscription processing w/out updating the subscription list.
int	unsubscribe_ifs (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0)
	Unsubscribe from a multicast address on one or more network interface(s).
int	unsubscribe_i (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0)
	Do unsubscription processing w/out udpating subscription list.
Private Attributes
int	opts_
	Per-instance options..
ACE_INET_Addr	send_addr_
	Multicast address to which local <send> methods send datagrams.
ACE_TCHAR *	send_net_if_
	Network interface to which all <send> methods send multicast datagrams.

---

Detailed Description

Defines the ACE socket wrapper for UDP/IP multicast.

Supports multiple simultaneous subscriptions, unsubscription from one or all subscriptions, and independent send/recv address and interface specifications. Template parameters and/or ctor arguments determine per-instance optional functionality.

Note that multicast semantics and implementation details are _very_ environment-specific; this class is just a wrapper around the underlying implementation and does not try to normalize the concept of multicast communications.

Usage Notes:

• Send and Recv addresses and network interfaces, but not port#, are independent. While this instance is open, 1 send interface (and a default send address) is in effect and 0, 1, or multiple recv addresses/interfaces are in effect.
• The first <open>/<subscribe> invocation defines the network interface and default address used for all sends by this instance, defines the port# and optionally the multicast address bound to the underlying socket, and defines the (one) port# that is used for all subscribes (subsequent subscribes must pass the same port# or '0').
• The default loopback state is not explicitly set; the environment will determine the default state. Note that some environments (e.g. some Win32) do not allow the default to be changed, and that the semantics of loopback control are environment dependent (e.g. sender vs receiver control).
• In general, due to multicast design and implementation quirks/bugs, it is difficult to tell which address a received message was sent to or which interface it was received on (even if only one subscription is active). However; there are filtering options that can be applied, to narrow it down considerably.

Interface specification notes (for <subscribe> and <unsubscribe>):

• If net_if == 0, the null_iface_opt option determines whether only the system "default" interface or all interfaces is affected. Specifying "all" interfaces is supported only for environments for which <ACE_Sock_Connect::get_ip_interfaces> is properly implemented.
• Multiple subscriptions for the same address but different interfaces is normally supported, but re-subscription to an address/interface that is already subscribed is normally not allowed.
• The <net_if> interface specification syntax is environment-specific. UNIX systems will normally use device specifications such as "le0" or "elxl1", while other systems will use the IP address of the interface. Some platforms, such as pSoS, support only cardinal numbers as network interface specifications; for these platforms, just give these numbers in alphanumeric form and <subscribe> will convert them into numbers via <ACE_OS::atoi>.

---

Member Enumeration Documentation

enum ACE_SOCK_Dgram_Mcast::options

Option parameters. These control per-instance optional functionality. They are set via optional constructor arguments. Note: Certain option values are not valid for all environments (see comments in source file for environment-specific restrictions). Default values are always valid values for the compilation environment. Enumeration values: OPT_BINDADDR_NO  Disable address bind. (Bind only port.). OPT_BINDADDR_YES  Enable address bind. (Bind port and address.). DEFOPT_BINDADDR  Default value for BINDADDR option. (Environment-dependent.). OPT_NULLIFACE_ONE  If (net_if==NULL), use default interface. OPT_NULLIFACE_ALL  If (net_if==NULL), use all mcast interfaces. DEFOPT_NULLIFACE  Default value for NULLIFACE option. (Environment-dependent.). DEFOPTS  All default options.

---

Constructor & Destructor Documentation

ACE_SOCK_Dgram_Mcast::ACE_SOCK_Dgram_Mcast (  options    opts = DEFOPTS )

You must invoke <open> or <subscribe>, to create/bind a socket and define operational parameters, before performing any I/O with this instance.

ACE_SOCK_Dgram_Mcast::~ACE_SOCK_Dgram_Mcast (  void    )

The OPT_DTORUNSUB_YES_ option defines whether an explicit <unsusbcribe> is done by the destructor. If not, most systems will automatically unsubscribe upon the close of the socket.

---

Member Function Documentation

int ACE_SOCK_Dgram_Mcast::clear_subs_list (  void    )  [protected]

Empty the dynamic subscription list.

void ACE_SOCK_Dgram_Mcast::dump (  void    )  const

Dump the state of an object. Logs the setting of all options, the bound address, the send address and interface, and the list of current subscriptions. Reimplemented from ACE_SOCK_Dgram.

int ACE_SOCK_Dgram_Mcast::join (  const ACE_INET_Addr &    mcast_addr, int    reuse_addr = 1, const ACE_TCHAR *    net_if = 0 )

int ACE_SOCK_Dgram_Mcast::leave (  const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if = 0 )

int ACE_SOCK_Dgram_Mcast::make_multicast_ifaddr (  ip_mreq *    mreq, const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if )  [protected]

Create a multicast addr/if pair, in format useful for system calls. If mreq param is NULL, just verify the passed addr/interface specs.

int ACE_SOCK_Dgram_Mcast::make_multicast_ifaddr_i (  ip_mreq *    mreq, const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if = ACE_LIB_TEXT("le0") )  [protected]

Create a multicast addr/if pair. This method factors out common code called by <make_multicast_address> and <subscribe>.

int ACE_SOCK_Dgram_Mcast::open (  const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if = 0, int    reuse_addr = 1 )

This method is optional; if not explicitly invoked, it is invoked by the first <subscribe>, using the subscribed address/port# and network interface paramters. The <mcast_addr> parameter defines the default send address/port# and also the port# and, if the OPT_BINDADDR_YES option is used, the multicast address that is bound to this socket. If the <send_net_if> parameter != 0, it defines the network interface used for all sends by this instance, otherwise the system "default" interface is used. (The <send_net_if> parameter is ignored if this feature is not supported by the envriornment.) The port# in <mcast_addr> may be 0, in which case a system-assigned (ephemeral) port# is used for sending and receiving. If <reuse_addr> != 0, the SO_REUSEADDR option and, if it is supported, the SO_REUSEPORT option are enabled. Returns: -1 if the call fails. Failure can occur due to problems with the address, port#, and/or interface parameters or during system open() or socket option processing.

int ACE_SOCK_Dgram_Mcast::open_i (  const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if = 0, int    reuse_addr = 1 )  [protected]

Contains common open functionality so that inheriting classes can reuse it.

ASYS_INLINE ssize_t ACE_SOCK_Dgram_Mcast::send (  const iovec    iov[], int    n, int    flags = 0 )  const

Send <n> <iovecs>, using the multicast address and network interface defined by the first <open> or <subscribe>.

ASYS_INLINE ssize_t ACE_SOCK_Dgram_Mcast::send (  const void *    buf, size_t    n, int    flags = 0 )  const

Send <n> bytes in <buf>, using the multicast address and network interface defined by the first <open> or <subscribe>.

ASYS_INLINE int ACE_SOCK_Dgram_Mcast::set_option (  int    option, char    optval )

Set a socket option. Set an ip option that takes a char as input, such as <IP_MULTICAST_LOOP> or <IP_MULTICAST_TTL>. This is just a more concise, nice interface to a subset of possible <ACE_SOCK::set_option> calls, but only works for IPPROTO_IP or IPPROTO_IPV6 level options. Use <ACE_SOCK::set_option> directly to set anything else. Deprecated: { This method has been deprecated since it cannot be used easily with with IPv6 options.} Returns 0 on success, -1 on failure.

int ACE_SOCK_Dgram_Mcast::subscribe (  const ACE_INET_Addr &    mcast_addr, int    reuse_addr = 1, const ACE_TCHAR *    net_if = 0, int    protocol_family = PF_INET, int    protocol = 0 )

The given group is joined on the specified interface. If option OPT_NULLIFACE_ALL is used and <net_if> is = 0, the group is joined on all multicast capable interfaces (IFF supported). Multiple subscriptions to various address and interface combinations are supported and tracked. If this is the first invocation of <subscribe>, and <open> was not previously invoked, <open> will be invoked using <mcast_addr> for binding the socket and <net_if> as the interface for <send>. Returns: -1 if the call fails. Failure can occur due to problems with the address, port#, and/or interface parameters or during the subscription attempt. Once bind() has been invoked (by the first <open> or <subscribe>), returns errno of ENXIO if the port# is not 0 and does not match the bound port#, or if OPT_BINDADDR_YES option is used and the address does not match the bound address. Returns errno of ENODEV if the addr/port#/interface parameters appeared valid, but no subscription(s) succeeded. An error is unconditionally returned if option OPT_NULLIFACE_ALL is used, <net_if> is NULL, and <ACE_Sock_Connect::get_ip_interfaces> is not implemented in this environment. Note that the optional <reuse_addr> parameter does not apply to subscriptions; it is only used if <open> is implicitly invoked (see above). Deprecated: This method has been deprecated, please use join() instead. In addition, the following parameters have also been deprecated: <protocol_family> and <protocol> have no effect.

int ACE_SOCK_Dgram_Mcast::subscribe_i (  const ACE_INET_Addr &    mcast_addr, int    reuse_addr = 1, const ACE_TCHAR *    net_if = 0 )  [private]

Do subscription processing w/out updating the subscription list.

int ACE_SOCK_Dgram_Mcast::subscribe_ifs (  const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if, int    reuse_addr )  [private]

Subscribe to a multicast address on one or more network interface(s). (No QoS support.)

int ACE_SOCK_Dgram_Mcast::unsubscribe (  void    )

Unsubscribe all current subscriptions. Unsubscribe all active group/interface subscriptions (if any). Returns -1 if any unsubscribe failed, 0 if there are no errors or no current subscriptions. Deprecated: This method has been deprecated. Since a list of groups is not maintained (except when ACE_SOCK_DGRAM_MCAST_DUMPABLE is defined), it isn't possible to unsubscribe to all the groups without closing the socket. Therefore, if applications wish to unsubscribe to all groups without closing the socket, they much keep track of the subscriptions and call the above unsubscribe () for each.

int ACE_SOCK_Dgram_Mcast::unsubscribe (  const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if = 0, int    protocol_family = PF_INET, int    protocol = 0 )

The specified group/interface combination is unsubscribed. If option OPT_NULLIFACE_ALL is used and <net_if> is = 0, the group is unsubscribed from all interfaces (IFF supported). Returns: -1 if the unsubscribe failed. Most environments will return -1 if there was no active subscription for this address/interface combination. An error is unconditionally returned if option OPT_NULLIFACE_ALL is used, <net_if> is = 0, and <ACE_Sock_Connect::get_ip_interfaces> is not implemented in this environment (_even if_ the <subscribe> specifies a non- NULL <net_if>). Deprecated: This method has been deprecated. Please use leave() instead. In addition, <protocol_family> and <protocol> have no effect.

int ACE_SOCK_Dgram_Mcast::unsubscribe_i (  const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if = 0 )  [private]

Do unsubscription processing w/out udpating subscription list.

int ACE_SOCK_Dgram_Mcast::unsubscribe_ifs (  const ACE_INET_Addr &    mcast_addr, const ACE_TCHAR *    net_if = 0 )  [private]

Unsubscribe from a multicast address on one or more network interface(s).

---

Member Data Documentation

ACE_SOCK_Dgram_Mcast::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks. Reimplemented from ACE_SOCK_Dgram.

int ACE_SOCK_Dgram_Mcast::opts_ [private]

Per-instance options..

ACE_INET_Addr ACE_SOCK_Dgram_Mcast::send_addr_ [private]

Multicast address to which local <send> methods send datagrams.

ACE_TCHAR* ACE_SOCK_Dgram_Mcast::send_net_if_ [private]

Network interface to which all <send> methods send multicast datagrams.

---

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

• SOCK_Dgram_Mcast.h
• SOCK_Dgram_Mcast.cpp
• SOCK_Dgram_Mcast.i

---