## NAME

ACE_SOCK_Dgram_Mcast - Defines the member functions for the ACE socket wrapper for UDP/IP multicast.

## SYNOPSIS

    #include <ace/SOCK_Dgram_Mcast.h>

    class ACE_SOCK_Dgram_Mcast : public ACE_SOCK_Dgram
    {
      public:
        ACE_SOCK_Dgram_Mcast (void);
        ~ACE_SOCK_Dgram_Mcast (void);
        int subscribe (
            const ACE_INET_Addr &mcast_addr,
            int reuse_addr = 1,
            const ASYS_TCHAR *net_if = 0,
            int protocol_family = PF_INET,
            int protocol = 0
            );
        int subscribe (
            const ACE_INET_Addr &mcast_addr,
            const ACE_QoS_Params &qos_params,
            int reuse_addr = 1,
            const ASYS_TCHAR *net_if = 0,
            int protocol_family = PF_INET,
            int protocol = 0
            );
        int unsubscribe (
            const ACE_INET_Addr &mcast_addr,
            const ASYS_TCHAR *net_if = 0,
            int protocol_family = PF_INET,
            int protocol = 0
            );
        int unsubscribe (void);
        ssize_t send (const void *buf, size_t n, int flags = 0) const;
        ssize_t send (const iovec iov[], size_t n, int flags = 0) const;
        int set_option (int option, char optval);
        void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
      private:
        int open (
            const ACE_Addr &mcast_addr,
            int protocol_family = PF_INET,
            int protocol = 0,
            int reuse_addr = 0
            );
        int open (
            const ACE_Addr &mcast_addr,
            const ACE_QoS_Params &qos_params,
            int protocol_family = PF_INET,
            int protocol = 0,
            ACE_Protocol_Info *protocolinfo = 0,
            ACE_SOCK_GROUP g = 0,
            u_long flags = 0,
            int reuse_addr = 0
            );
        int subscribe_ifs (
            const ACE_INET_Addr &mcast_addr,
            const ASYS_TCHAR *net_if,
            int protocol_family,
            int protocol,
            int reuse_addr
            );
        int subscribe_ifs (
            const ACE_INET_Addr &mcast_addr,
            const ACE_QoS_Params &qos_params,
            const ASYS_TCHAR *net_if,
            int protocol_family,
            int protocol,
            int reuse_addr
            );
        int unsubscribe_ifs (
            const ACE_INET_Addr &mcast_addr,
            const ASYS_TCHAR *net_if = 0,
            int protocol_family = PF_INET,
            int protocol = 0
            );
        ssize_t send (
            const void *buf,
            size_t n,
            const ACE_Addr &addr,
            int flags = 0
            ) const;
        ssize_t send (
            const iovec iov[],
            size_t n,
            const ACE_Addr &addr,
            int flags = 0
            ) const;
        int make_multicast_address (
            const ACE_INET_Addr &mcast_addr,
            const ASYS_TCHAR *net_if = ASYS_TEXT ("le0")
            );
        int make_multicast_address_i (
            const ACE_INET_Addr &mcast_addr,
            ip_mreq& multicast_address,
            const ASYS_TCHAR *net_if = ASYS_TEXT ("le0")
            );
        ACE_INET_Addr mcast_addr_;
        ip_mreq mcast_request_if_;
    };

## Initialization routine.

    ACE_SOCK_Dgram_Mcast (void);

Note that there is no public `open` method. Therefore, this class cannot be used unless you `subscribe` to a multicast group. If you just want to send (and not listen) to a multicast group, use `ACE_SOCK_Dgram` or `ACE_SOCK_CODgram` instead.

    ~ACE_SOCK_Dgram_Mcast (void);

Default dtor.

## Multicast group management routines.

    int subscribe (
        const ACE_INET_Addr &mcast_addr,
        int reuse_addr = 1,
        const ASYS_TCHAR *net_if = 0,
        int protocol_family = PF_INET,
        int protocol = 0
        );

This is a BSD-style method (i.e., no QoS) for joining a multicast group. The network interface device driver is instructed to accept datagrams with `mcast_addr` multicast addresses. If the socket has already been opened, `subscribe` closes the socket and opens a new socket bound to the `mcast_addr`.

The `net_if` interface is hardware specific, e.g., use "netstat -i" to find whether your interface is, such as "le0" or something else. If net_if == 0, `subscribe` uses the default mcast interface. Returns: -1 on error, else 0.

Note that some platforms, such as pSoS, support only number, not names, for network interfaces. For these platforms, just give these numbers in alphanumeric form and `subscribe` will convert them into numbers via `ACE_OS::atoi`.

    int subscribe (
        const ACE_INET_Addr &mcast_addr,
        const ACE_QoS_Params &qos_params,
        int reuse_addr = 1,
        const ASYS_TCHAR *net_if = 0,
        int protocol_family = PF_INET,
        int protocol = 0
        );

This is a QoS-enabled method for joining a multicast group, which passes `qos_params` via `ACE_OS::join_leaf`. The network interface device driver is instructed to accept datagrams with `mcast_addr` multicast addresses. If the socket has already been opened, `subscribe` closes the socket and opens a new socket bound to the `mcast_addr`.

The `net_if` interface is hardware specific, e.g., use "netstat -i" to find whether your interface is, such as "le0" or something else. If net_if == 0, `subscribe` uses the default mcast interface. Returns: a 0 on success or -1 on failure.

Note that some platforms, such as pSoS, support only number, not names, for network interfaces. For these platforms, just give these numbers in alphanumeric form and `subscribe` will convert them into numbers via `ACE_OS::atoi`.

    int unsubscribe (
        const ACE_INET_Addr &mcast_addr,
        const ASYS_TCHAR *net_if = 0,
        int protocol_family = PF_INET,
        int protocol = 0
        );

Leave a multicast group identified by `mcast_addr`. The `net_if` interface is hardware specific. Use something like "netstat -i" to find whether your interface is, such as "le0" or something else. If `net_if` == 0, `subscribe` uses the default mcast interface. Returns: -1 on error, else 0.

Note that some platforms, such as pSoS, support only number, not names, for network interfaces. For these platforms, just give these numbers in alphanumeric form and `subscribe` will convert them into numbers via `ACE_OS::atoi`.

    int unsubscribe (void);

Unsubscribe from a multicast group. Returns 0 on success, -1 on failure.

## Data transfer routines.

    ssize_t send (const void *buf, size_t n, int flags = 0) const;

Send `n` bytes in `buf`.

    ssize_t send (const iovec iov[], size_t n, int flags = 0) const;

Send `n` `iovecs`.

## Options.

    int set_option (int option, char optval);

Set an ip option that takes a char as input, such as `IP_MULTICAST_LOOP`. This is just a more concise nice interface to a subset of possible `ACE_SOCK::set_option` calls. Returns 0 on success, -1 on failure.

    void dump (void) const;

Dump the state of an object.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

## AUTHORS

Irfan Pyrali `irfan@cs.wustl.edu`, Tim Harrison `harrison@cs.wustl.edu`, and Douglas C. Schmidt `schmidt@cs.wustl.edu`

## LIBRARY

ace