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:

Inheritance graph
[legend]
Collaboration diagram for ACE_SOCK_Dgram_Mcast:

Collaboration graph
[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 Member Functions

 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 join (const ACE_INET_Addr &mcast_addr, int reuse_addr=1, const ACE_TCHAR *net_if=0)
int leave (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0)
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 Member Functions

int open_i (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0, int reuse_addr=1)
int clear_subs_list (void)
 Empty the dynamic subscription list.

Private Member Functions

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_TCHARsend_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:

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


Member Enumeration Documentation

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.
Enumerator:
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  Define the interpretation of 'NULL' as a recv interface specification.

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 ( ACE_SOCK_Dgram_Mcast::options  opts = DEFOPTS  ) 

Ctor - Create an unitialized instance and define per-instance optional functionality. 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   ) 

Dtor - Release all resources and implicitly or explicitly unsubscribe from all currently subscribed groups. 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 
)

Join a multicast group on a given interface (or all interfaces, if supported). 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).

Uses the mcast_addr to determine protocol_family, and protocol which we always pass as 0 anyway.

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

Leave a multicast group on a given interface (or all interfaces, if supported). 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>).

leave() replaces unsubscribe() and uses mcast_addr to determine protocol_family, and protocol which we always pass as 0 anyway.

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

Explicitly open/bind the socket and define the network interface and default multicast address used for sending messages. This method is optional; if not explicitly invoked, it is invoked by the first <subscribe>, using the subscribed address/port# and network interface parameters. 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.

ACE_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>.

ACE_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>.

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_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.

Returns 0 on success, -1 on failure.

Deprecated:
This method has been deprecated since it cannot be used easily with with IPv6 options. Use ACE_SOCK::set_option instead.

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_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

Declare the dynamic allocation hooks.

Reimplemented from ACE_SOCK_Dgram.

Per-instance options..

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

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


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

Generated on Mon Feb 9 20:34:13 2009 for ACE by  doxygen 1.5.8