# Mcast

## Name

Mcast -- IP Multicast socket

## Synopsis

    struct      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

### >struct GMcastSocket

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

socket : | a GMcastSocket

### >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 child of GUdpSocket.

MS : | a GMcastSocket