ACE  6.3.3
Public Types | Public Member Functions | Public Attributes | Protected Member Functions | Private Member Functions | Private Attributes | List of all members
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]

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 Types inherited from ACE_SOCK_Dgram
typedef ACE_INET_Addr PEER_ADDR
 

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. More...
 
void dump (void) const
 Dump the state of an object. More...
 
void opts (int opts)
 
int opts () const
 Read acessor for the constructor options (. More...
 
- Public Member Functions inherited from ACE_SOCK_Dgram
 ACE_SOCK_Dgram (void)
 Default constructor. More...
 
 ACE_SOCK_Dgram (const ACE_Addr &local, int protocol_family=ACE_PROTOCOL_FAMILY_INET, int protocol=0, int reuse_addr=0)
 
 ACE_SOCK_Dgram (const ACE_Addr &local, int protocol_family, int protocol, ACE_Protocol_Info *protocolinfo, ACE_SOCK_GROUP g=0, u_long flags=0, int reuse_addr=0)
 
int open (const ACE_Addr &local, int protocol_family=ACE_PROTOCOL_FAMILY_INET, int protocol=0, int reuse_addr=0)
 
int open (const ACE_Addr &local, int protocol_family, int protocol, ACE_Protocol_Info *protocolinfo, ACE_SOCK_GROUP g=0, u_long flags=0, int reuse_addr=0)
 
 ~ACE_SOCK_Dgram (void)
 Default dtor. More...
 
ssize_t send (const void *buf, size_t n, const ACE_Addr &addr, int flags=0) const
 Send an n byte buf to the datagram socket (uses <sendto(3)>). More...
 
ssize_t recv (void *buf, size_t n, ACE_Addr &addr, int flags=0) const
 
ssize_t recv (iovec *io_vec, ACE_Addr &addr, int flags=0, const ACE_Time_Value *timeout=0) const
 
ssize_t send (const iovec iov[], int n, const ACE_Addr &addr, int flags=0) const
 
ssize_t recv (iovec iov[], int n, ACE_Addr &addr, int flags=0) const
 
ssize_t recv (void *buf, size_t n, ACE_Addr &addr, int flags, const ACE_Time_Value *timeout) const
 
ssize_t send (const void *buf, size_t n, const ACE_Addr &addr, int flags, const ACE_Time_Value *timeout) const
 
ssize_t send (const iovec buffers[], int buffer_count, size_t &number_of_bytes_sent, int flags, const ACE_Addr &addr, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const
 
ssize_t recv (iovec buffers[], int buffer_count, size_t &number_of_bytes_recvd, int &flags, ACE_Addr &addr, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const
 
ssize_t send (const void *buf, size_t n, const ACE_Addr &addr, int flags, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const
 Send an n byte buf to the datagram socket (uses <WSASendTo>). More...
 
ssize_t recv (void *buf, size_t n, ACE_Addr &addr, int flags, ACE_OVERLAPPED *overlapped, ACE_OVERLAPPED_COMPLETION_FUNC func) const
 
void dump (void) const
 Dump the state of an object. More...
 
int set_nic (const ACE_TCHAR *net_if, int addr_family=AF_UNSPEC)
 Set NIC to use as multicast interface. More...
 
- Public Member Functions inherited from ACE_SOCK
int set_option (int level, int option, void *optval, int optlen) const
 Wrapper around the setsockopt system call. More...
 
int get_option (int level, int option, void *optval, int *optlen) const
 Wrapper around the getsockopt system call. More...
 
int close (void)
 
int get_local_addr (ACE_Addr &) const
 
int get_remote_addr (ACE_Addr &) const
 
void dump (void) const
 Dump the state of an object. More...
 
int open (int type, int protocol_family, int protocol, int reuse_addr)
 Wrapper around the BSD-style socket system call (no QoS). More...
 
int open (int type, int protocol_family, int protocol, ACE_Protocol_Info *protocolinfo, ACE_SOCK_GROUP g, u_long flags, int reuse_addr)
 Wrapper around the QoS-enabled WSASocket function. More...
 
- Public Member Functions inherited from ACE_IPC_SAP
int control (int cmd, void *) const
 Interface for <ioctl>. More...
 
int enable (int value) const
 
int disable (int value) const
 
ACE_HANDLE get_handle (void) const
 Get the underlying handle. More...
 
void set_handle (ACE_HANDLE handle)
 Set the underlying handle. More...
 
void dump (void) const
 Dump the state of an object. More...
 

Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...
 
- Public Attributes inherited from ACE_SOCK_Dgram
 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...
 
- Public Attributes inherited from ACE_SOCK
 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...
 
- Public Attributes inherited from ACE_IPC_SAP
 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...
 

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. More...
 
- Protected Member Functions inherited from ACE_SOCK_Dgram
int shared_open (const ACE_Addr &local, int protocol_family)
 Open is shared by this and by <LSOCK_Dgram>. More...
 
int make_multicast_ifaddr (ip_mreq *mreq, const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if)
 
int make_multicast_ifaddr6 (ipv6_mreq *mreq, const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if)
 
- Protected Member Functions inherited from ACE_SOCK
 ACE_SOCK (int type, int protocol_family, int protocol=0, int reuse_addr=0)
 
 ACE_SOCK (int type, int protocol_family, int protocol, ACE_Protocol_Info *protocolinfo, ACE_SOCK_GROUP g, u_long flags, int reuse_addr)
 
 ACE_SOCK (void)
 
 ~ACE_SOCK (void)
 Protected destructor. More...
 
- Protected Member Functions inherited from ACE_IPC_SAP
 ACE_IPC_SAP (void)
 Default constructor. More...
 
 ~ACE_IPC_SAP (void)
 Protected destructor. More...
 

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)
 
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). More...
 
int unsubscribe_i (const ACE_INET_Addr &mcast_addr, const ACE_TCHAR *net_if=0)
 

Private Attributes

int opts_
 Per-instance options.. More...
 
ACE_INET_Addr send_addr_
 Multicast address to which local send() methods send datagrams. More...
 
ACE_TCHARsend_net_if_
 Network interface to which all send() methods send multicast datagrams. More...
 

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. Constructor 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 an optional constructor argument.

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

Note
This might seem odd, but we need a way to distinguish between default behavior, which might or might not be to bind, and explicitly choosing to bind or not to bind–which "is the question." ;-)
OPT_BINDADDR_YES 

Enable address bind. (Bind port and address.)

DEFOPT_BINDADDR 

Default value for BINDADDR option. (Environment-dependent.)

At least some Win32 OS's can not bind mcast addr, so disable it. General-purpose default behavior is 'disabled', since effect is environment-specific and side-effects might be surprising.

OPT_NULLIFACE_ONE 

Supported values: If (net_if==NULL), use default interface.

Note
This might seem odd, but we need a way to distinguish between default behavior, which might or might not be to bind, and explicitly choosing to bind or not to bind–which "is the question." ;-)
OPT_NULLIFACE_ALL 

If (net_if==NULL), use all mcast interfaces.

DEFOPT_NULLIFACE 

Default value for NULLIFACE option. (Environment-dependent.)

This is the (ad-hoc) legacy behavior for Win32/WinSock.

Note
Older version of WinSock/MSVC may not get all multicast-capable interfaces (e.g. PPP interfaces).
DEFOPTS 

All default options.

Constructor & Destructor Documentation

ACE_SOCK_Dgram_Mcast::ACE_SOCK_Dgram_Mcast ( ACE_SOCK_Dgram_Mcast::options  opts = DEFOPTS)

Create an unitialized instance and define per-instance optional functionality. You must invoke open() or join(), 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  )

Release all resources and implicitly or explicitly unsubscribe from all currently subscribed groups. The OPT_DTORUNSUB_YES_ option defines whether an explicit unsubscribe() 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.

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 join(), using the subscribed address/port number and network interface parameters.

Parameters
mcast_addrDefines the default send address/port number and, if the OPT_BINDADDR_YES option is used, the multicast address that is bound to this socket. The port number in mcast_addr may be 0, in which case a system-assigned (ephemeral) port number is used for sending and receiving.
net_ifIf net_if is not 0, it defines the network interface used for all sends by this instance, otherwise the system default interface is used. (The net_if parameter is ignored if this feature is not supported by the environment.)
reuse_addrIf reuse_addr is not 0, the SO_REUSEADDR option and, if it is supported, the SO_REUSEPORT option are enabled.
Return values
0on success
-1if 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.

void ACE_SOCK_Dgram_Mcast::opts ( int  opts)
inline

Override write acessor for the constructor options (

See also
enum options above) This class is typically default instantiated in a connection handler templated framework so these cannot be specified on construction.
int ACE_SOCK_Dgram_Mcast::opts ( ) const
inline

Read acessor for the constructor options (.

See also
enum options above)
ssize_t ACE_SOCK_Dgram_Mcast::send ( const void *  buf,
size_t  n,
int  flags = 0 
) const
inline

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

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

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

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

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. (Layered method for <subscribe> processing).

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. (Layered method for <unsubscribe> processing).

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.

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: