## UDP UDP — UDP socket |

## Synopsis

    #include <gnet.h>

                        GUdpSocket;
    GUdpSocket*         gnet_udp_socket_new                 (void);
    GUdpSocket*         gnet_udp_socket_new_with_port       (gint port);
    GUdpSocket*         gnet_udp_socket_new_full            (const GInetAddr *iface,
                                                             gint port);
    void                gnet_udp_socket_delete              (GUdpSocket *socket);
    void                gnet_udp_socket_ref                 (GUdpSocket *socket);
    void                gnet_udp_socket_unref               (GUdpSocket *socket);
    gint                gnet_udp_socket_send                (GUdpSocket *socket,
                                                             const gchar *buffer,
                                                             gint length,
                                                             const GInetAddr *dst);
    gint                gnet_udp_socket_receive             (GUdpSocket *socket,
                                                             gchar *buffer,
                                                             gint length,
                                                             GInetAddr **src);
    gboolean            gnet_udp_socket_has_packet          (const GUdpSocket *socket);
    GIOChannel*         gnet_udp_socket_get_io_channel      (GUdpSocket *socket);
    GInetAddr*          gnet_udp_socket_get_local_inetaddr  (const GUdpSocket *socket);
    gint                gnet_udp_socket_get_ttl             (const GUdpSocket *socket);
    gint                gnet_udp_socket_set_ttl             (GUdpSocket *socket,
                                                             gint ttl);

## Description

This module provides support for UDP sockets. UDP is an internet protocol that transfers packets by best-effort delivery. Packets may be lost or arrive out-of-order. Use TCP if your protocol requires data transfered reliably and in-order -- most do.

A UDP socket is represented by a GUdpSocket structure. To create a GUdpSocket, call `gnet_udp_socket_new()`, `gnet_udp_socket_new_with_port()`, or `gnet_udp_socket_new_full()`.

To send a packet, call `gnet_udp_socket_send()`. To receive a packet, call `gnet_udp_socket_receive()`. `gnet_udp_socket_send()` will block if the OS cannot buffer the packet immediately. `gnet_udp_socket_receive()` will block until there is a packet available to receive. Call `gnet_udp_socket_has_packet()` to determine whether a packet is available immediately. A more elegant method is to get the GIOChannel and add a read watch. A callback will be called when a packet is available. Note that a UDP socket's GIOChannel is not a normal GIOChannel -- it should not be written to or read from directly.

Packets have a time-to-live (TTL) field. This field is decremented before a router forwards the packet. If the TTL reaches zero, the packet is dropped. The TTL can be set by calling `gnet_udp_socket_get_ttl()`. The default value is sufficient for most applications.

## Details

### GUdpSocket

    typedef struct _GUdpSocket GUdpSocket;

A GUdpSocket structure represents a UDP socket. The implementation is hidden.

### gnet_udp_socket_new ()

    GUdpSocket*         gnet_udp_socket_new                 (void);

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

Returns : | a new GUdpSocket; NULL on error.

### gnet_udp_socket_new_with_port ()

    GUdpSocket*         gnet_udp_socket_new_with_port       (gint port);

Creates a GUdpSocket bound to all interfaces and port `port`. If `port` is 0, an arbitrary port will be used.

`port` : | port to bind to (0 for an arbitrary port)
Returns : | a new GUdpSocket; NULL on error.

### gnet_udp_socket_new_full ()

    GUdpSocket*         gnet_udp_socket_new_full            (const GInetAddr *iface,
                                                             gint port);

Creates a GUdpSocket 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.

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

### gnet_udp_socket_delete ()

    void                gnet_udp_socket_delete              (GUdpSocket *socket);

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

`socket` : | a GUdpSocket, or NULL

### gnet_udp_socket_ref ()

    void                gnet_udp_socket_ref                 (GUdpSocket *socket);

Adds a reference to a GUdpSocket.

`socket` : | GUdpSocket to reference

### gnet_udp_socket_unref ()

    void                gnet_udp_socket_unref               (GUdpSocket *socket);

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

`socket` : | a GUdpSocket

### gnet_udp_socket_send ()

    gint                gnet_udp_socket_send                (GUdpSocket *socket,
                                                             const gchar *buffer,
                                                             gint length,
                                                             const GInetAddr *dst);

Sends data to a host using a GUdpSocket.

`socket` : | a GUdpSocket
`buffer` : | buffer to send
`length` : | length of `buffer`
`dst` : | destination address
Returns : | 0 if successful; something else on error.

### gnet_udp_socket_receive ()

    gint                gnet_udp_socket_receive             (GUdpSocket *socket,
                                                             gchar *buffer,
                                                             gint length,
                                                             GInetAddr **src);

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

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

### gnet_udp_socket_has_packet ()

    gboolean            gnet_udp_socket_has_packet          (const GUdpSocket *socket);

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

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

### gnet_udp_socket_get_io_channel ()

    GIOChannel*         gnet_udp_socket_get_io_channel      (GUdpSocket *socket);

Gets the GIOChannel of a GUdpSocket.

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

Every GUdpSocket 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.

Before deleting the UDP socket, make sure to remove any watches you have added with `g_io_add_watch()` again with `g_source_remove()` using the integer id returned by `g_io_add_watch()`. You may find your program stuck in a busy loop at 100% CPU utilisation if you forget to do this.

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

### gnet_udp_socket_get_local_inetaddr ()

    GInetAddr*          gnet_udp_socket_get_local_inetaddr  (const GUdpSocket *socket);

Gets the local host's address from a GUdpSocket.

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

### gnet_udp_socket_get_ttl ()

    gint                gnet_udp_socket_get_ttl             (const GUdpSocket *socket);

Gets the time-to-live (TTL) default of a GUdpSocket. All UDP 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.

`socket` : | a GUdpSocket
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_udp_socket_set_ttl ()

    gint                gnet_udp_socket_set_ttl             (GUdpSocket *socket,
                                                             gint ttl);

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

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