## Mcast

Mcast — IP Multicast socket

## Synopsis

    #include <gnet.h>

                        GMcastSocket;
    GMcastSocket*       gnet_mcast_socket_new               (void);
    GMcastSocket*       gnet_mcast_socket_new_with_port     (gint port);
    GMcastSocket*       gnet_mcast_socket_new_full          (const GInetAddr *iface,
                                                             gint port);
    void                gnet_mcast_socket_delete            (GMcastSocket *socket);
    void                gnet_mcast_socket_ref               (GMcastSocket *socket);
    void                gnet_mcast_socket_unref             (GMcastSocket *socket);
    GIOChannel*         gnet_mcast_socket_get_io_channel    (GMcastSocket *socket);
    GInetAddr*          gnet_mcast_socket_get_local_inetaddr
                                                            (const GMcastSocket *socket);
    gint                gnet_mcast_socket_join_group        (GMcastSocket *socket,
                                                             const GInetAddr *inetaddr);
    gint                gnet_mcast_socket_leave_group       (GMcastSocket *socket,
                                                             const GInetAddr *inetaddr);
    gint                gnet_mcast_socket_get_ttl           (const GMcastSocket *socket);
    gint                gnet_mcast_socket_set_ttl           (GMcastSocket *socket,
                                                             gint ttl);
    gint                gnet_mcast_socket_send              (GMcastSocket *socket,
                                                             const gchar *buffer,
                                                             gint length,
                                                             const GInetAddr *dst);
    gint                gnet_mcast_socket_receive           (GMcastSocket *socket,
                                                             gchar *buffer,
                                                             gint length,
                                                             GInetAddr **src);
    gboolean            gnet_mcast_socket_has_packet        (const GMcastSocket *socket);
    gint                gnet_mcast_socket_is_loopback       (const GMcastSocket *socket);
    gint                gnet_mcast_socket_set_loopback      (GMcastSocket *socket,
                                                             gboolean enable);
    #define             gnet_mcast_socket_to_udp_socket     (MS)

## Description

The Mcast module provides support for IP Multicast sockets. IP Multicast allows you to send one packet to many receivers at once. Unfortunately, IP Multicast is not widely available. IP Multicast is built on UDP.

An IP Multicast socket is represented by a GMcastSocket stucture. To create a GMcastSocket, call `gnet_mcast_socket_new()`, `gnet_mcast_socket_new_with_port()`, or `gnet_mcast_socket_new_full()`. Then call `gnet_mcast_socket_join_group()` to join a multicast group. To leave the group, call `gnet_mcast_socket_leave_group()`.

Use `gnet_mcast_socket_set_loopback()` to set whether packets sent by the host will also be received by the host. Applications typically disable loopback.

## Details

### GMcastSocket

    typedef struct _GMcastSocket GMcastSocket;

A GMcastSocket structure represents a IP Multicast socket. The implementation is hidden. A GMcastSocket is child of GUdpSocket. Use `gnet_mcast_socket_to_udp_socket()` to safely cast a GMcastSocket to a GUdpSocket.

### gnet_mcast_socket_new ()

    GMcastSocket*       gnet_mcast_socket_new               (void);

Creates a GMcastSocket bound to all interfaces and an arbitrary port.

Returns : | a new GMcastSocket; NULL on error.

### gnet_mcast_socket_new_with_port ()

    GMcastSocket*       gnet_mcast_socket_new_with_port     (gint port);

Creates a GMcastSocket bound to all interfaces and port `port`. If `port` is 0, an arbitrary port will be used. Use this constructor if you know the port of the group you will join. Most applications will use this constructor.

`port` : | port to bind to
Returns : | a new GMcastSocket; NULL on error.

### gnet_mcast_socket_new_full ()

    GMcastSocket*       gnet_mcast_socket_new_full          (const GInetAddr *iface,
                                                             gint port);

Creates a GMcastSocket bound to interface `iface` and port `port`. If `iface` is NULL, all interfaces will be used. If `port` is 0, an arbitrary port will be used. To receive packets from this group, call `gnet_mcast_socket_join_group()` next. Loopback is disabled by default.

`iface` : | interface to bind to (NULL for all interfaces)
`port` : | port to bind to (0 for an arbitrary port)
Returns : | a new GMcastSocket; NULL on error.

### gnet_mcast_socket_delete ()

    void                gnet_mcast_socket_delete            (GMcastSocket *socket);

Deletes a GMcastSocket. Does nothing if `socket` is NULL.

`socket` : | a GMcastSocket, or NULL

### gnet_mcast_socket_ref ()

    void                gnet_mcast_socket_ref               (GMcastSocket *socket);

Adds a reference to a GMcastSocket.

`socket` : | a GMcastSocket

### gnet_mcast_socket_unref ()

    void                gnet_mcast_socket_unref             (GMcastSocket *socket);

Removes a reference from a GMcastSocket. A GMcastSocket is deleted when the reference count reaches 0.

`socket` : | a GMcastSocket

### gnet_mcast_socket_get_io_channel ()

    GIOChannel*         gnet_mcast_socket_get_io_channel    (GMcastSocket *socket);

Gets the GIOChannel of a GMcastSocket.

Use the channel with `g_io_add_watch()` to check if the socket is readable or writable. If the channel is readable, call `gnet_mcast_socket_receive()` to receive a packet. If the channel is writable, call `gnet_mcast_socket_send()` to send a packet. This is not a normal giochannel - do not read from or write to it.

Every GMcastSocket has one and only one GIOChannel. If you ref the channel, then you must unref it eventually. Do not close the channel. The channel is closed by GNet when the socket is deleted.

`socket` : | a GMcastSocket
Returns : | a GIOChannel.

### gnet_mcast_socket_get_local_inetaddr ()

    GInetAddr*          gnet_mcast_socket_get_local_inetaddr
                                                            (const GMcastSocket *socket);

Gets the local host's address from a GMcastSocket.

`socket` : | a GMcastSocket
Returns : | a GInetAddr.

### gnet_mcast_socket_join_group ()

    gint                gnet_mcast_socket_join_group        (GMcastSocket *socket,
                                                             const GInetAddr *inetaddr);

Joins a multicast group. Join only one group per socket.

`socket` : | a GMcastSocket
`inetaddr` : | address of the group
Returns : | 0 on success.

### gnet_mcast_socket_leave_group ()

    gint                gnet_mcast_socket_leave_group       (GMcastSocket *socket,
                                                             const GInetAddr *inetaddr);

Leaves a mulitcast group.

`socket` : | a GMcastSocket
`inetaddr` : | address of the group
Returns : | 0 on success.

### gnet_mcast_socket_get_ttl ()

    gint                gnet_mcast_socket_get_ttl           (const GMcastSocket *socket);

Gets the multicast time-to-live (TTL) of a GMcastSocket. All IP multicast packets have a TTL field. This field is decremented by a router before it forwards the packet. If the TTL reaches zero, the packet is discarded. The default value is sufficient for most applications.

The table below shows the scope for a given TTL. The scope is only an estimate.

Table 1. TTL and scope

TTL | Scope
--- | ---
0 | node local
1 | link local
2-32 | site local
33-64 | region local
65-128 | continent local
129-255 | unrestricted (global)

`socket` : | a GMcastSocket
Returns : | the TTL (an integer between 0 and 255), -1 if the kernel default is being used, or an integer less than -1 on error.

### gnet_mcast_socket_set_ttl ()

    gint                gnet_mcast_socket_set_ttl           (GMcastSocket *socket,
                                                             gint ttl);

Sets the time-to-live (TTL) default of a GMcastSocket. Set the TTL to -1 to use the kernel default. The default value is sufficient for most applications.

`socket` : | a GMcastSocket
`ttl` : | value to set TTL to
Returns : | 0 if successful.

### gnet_mcast_socket_send ()

    gint                gnet_mcast_socket_send              (GMcastSocket *socket,
                                                             const gchar *buffer,
                                                             gint length,
                                                             const GInetAddr *dst);

Sends data to a host using a GMcastSocket.

`socket` : | a GMcastSocket
`buffer` : | buffer to send
`length` : | length of buffer
`dst` : | destination address
Returns : | 0 if successful.

### gnet_mcast_socket_receive ()

    gint                gnet_mcast_socket_receive           (GMcastSocket *socket,
                                                             gchar *buffer,
                                                             gint length,
                                                             GInetAddr **src);

Receives data using a GMcastSocket. If `src` is set, the source address is stored in the location `src` points to. The address is caller owned.

`socket` : | a GMcastSocket
`buffer` : | buffer to write to
`length` : | length of `buffer`
`src` : | pointer to source address (optional)
Returns : | the number of bytes received, -1 if unsuccessful.

### gnet_mcast_socket_has_packet ()

    gboolean            gnet_mcast_socket_has_packet        (const GMcastSocket *socket);

Tests if a GMcastSocket has a packet waiting to be received.

`socket` : | a GMcastSocket
Returns : | TRUE if there is packet waiting, FALSE otherwise.

### gnet_mcast_socket_is_loopback ()

    gint                gnet_mcast_socket_is_loopback       (const GMcastSocket *socket);

Checks if a GMcastSocket has loopback enabled. If loopback is enabled, all packets sent by the host will also be received by the host. Loopback is disabled by default.

`socket` : | a GMcastSocket
Returns : | 0 if loopback is disabled, 1 if enabled, and -1 on error.

### gnet_mcast_socket_set_loopback ()

    gint                gnet_mcast_socket_set_loopback      (GMcastSocket *socket,
                                                             gboolean enable);

Enables (or disables) loopback on a GMcastSocket. Loopback is disabled by default.

`socket` : | a GMcastSocket
`enable` : | should loopback be enabled?
Returns : | 0 if successful.

### gnet_mcast_socket_to_udp_socket()

    #define gnet_mcast_socket_to_udp_socket(MS) ((GUdpSocket*) (MS))

Converts a GMcastSocket to a GUdpSocket. A GMcastSocket is a child of GUdpSocket.

`MS` : | a GMcastSocket