Gnet Network Library Reference Manual
<<< Previous Page | Home | Up |

# UDP module

## Name

UDP module -- UDP (datagram) functions.

## Synopsis

    GUdpSocket* gnet_udp_socket_new             (void);
    GUdpSocket* gnet_udp_socket_port_new        (const gint port);
    void        gnet_udp_socket_delete          (GUdpSocket *s);
    void        gnet_udp_socket_ref             (GUdpSocket *s);
    void        gnet_udp_socket_unref           (GUdpSocket *s);
    gint        gnet_udp_socket_send            (const GUdpSocket *s,
                                                 const GUdpPacket *packet);
    gint        gnet_udp_socket_receive         (const GUdpSocket *s,
                                                 GUdpPacket *packet);
    gboolean    gnet_udp_socket_has_packet      (const GUdpSocket *s);
    GIOChannel* gnet_udp_socket_get_iochannel   (GUdpSocket *socket);
    gint        gnet_udp_socket_get_ttl         (GUdpSocket *us);
    gint        gnet_udp_socket_set_ttl         (GUdpSocket *us,
                                                 int val);
    gint        gnet_udp_socket_get_mcast_ttl   (GUdpSocket *us);
    gint        gnet_udp_socket_set_mcast_ttl   (GUdpSocket *us,
                                                 gint val);
    GUdpPacket* gnet_udp_packet_receive_new     (gint8 *data,
                                                 gint length);
    GUdpPacket* gnet_udp_packet_send_new        (gint8 *data,
                                                 gint length,
                                                 GInetAddr *addr);
    void        gnet_udp_packet_delete          (GUdpPacket *packet);

## Description

A UdpSocket represents an open UDP (or datagram) socket. Create a UdpSocket by calling udp_socket_new() or udp_socket_port_new().

A UdpPacket represents a packet that can be sent or received via a UdpSocket (or McastSocket). Create a UdpPacket by calling udp_packet_receive_new or udp_packet_send_new depending on whether you plan to use this structure to send or receive the packet.

If you are writing a new protocol, you probably want to use TCP, not UDP.

## Details

### gnet_udp_socket_new ()

    GUdpSocket* gnet_udp_socket_new             (void);

Create and open a new UDP socket with any port.

Returns : | a new GUdpSocket, or NULL if there was a failure.

### gnet_udp_socket_port_new ()

    GUdpSocket* gnet_udp_socket_port_new        (const gint port);

Create and open a new UDP socket with a specific port.

`port` : | port number for the socket.
Returns : | a new GUdpSocket, or NULL if there was a failure.

### gnet_udp_socket_delete ()

    void        gnet_udp_socket_delete          (GUdpSocket *s);

Close and delete a UDP socket.

`s` : | GUdpSocket to delete.

### gnet_udp_socket_ref ()

    void        gnet_udp_socket_ref             (GUdpSocket *s);

Increment the reference counter of the GUdpSocket.

`s` : | GUdpSocket to reference

### gnet_udp_socket_unref ()

    void        gnet_udp_socket_unref           (GUdpSocket *s);

Remove a reference from the GUdpSocket. When reference count reaches 0, the socket is deleted.

`s` : | GUdpSocket to unreference

### gnet_udp_socket_send ()

    gint        gnet_udp_socket_send            (const GUdpSocket *s,
                                                 const GUdpPacket *packet);

`s` : |
`packet` : |
Returns : |

### gnet_udp_socket_receive ()

    gint        gnet_udp_socket_receive         (const GUdpSocket *s,
                                                 GUdpPacket *packet);

Receive a packet using the UDP socket.

`s` : | GUdpSocket to receive from.
`packet` : | Packet to receive.
Returns : | the number of bytes received, -1 if unsuccessful.

### gnet_udp_socket_has_packet ()

    gboolean    gnet_udp_socket_has_packet      (const GUdpSocket *s);

Test if the socket has a receive packet. It's strongly recommended that you use a GIOChannel with a read watch instead of this function.

`s` : | GUdpSocket to check
Returns : | TRUE if there is packet waiting, FALSE otherwise.

### gnet_udp_socket_get_iochannel ()

    GIOChannel* gnet_udp_socket_get_iochannel   (GUdpSocket *socket);

Get a GIOChannel from the GUdpSocket.

THIS IS NOT A NORMAL GIOCHANNEL - DO NOT READ OR WRITE WITH IT.

Use the channel with g_io_add_watch() to do non-blocking IO (so if you do not want to do non-blocking IO, you do not need the channel). If you can read from the channel, use gnet_udp_socket_receive() to read a packet. If you can write to the channel, use gnet_udp_socket_send() to write a packet.

There is one channel for every socket. This function refs the channel before returning it. You should unref the channel when you are done with it. However, you should not close the channel - this is done when you delete the socket.

`socket` : | GUdpSocket to get GIOChannel from.
Returns : | A GIOChannel; NULL on failure.

### gnet_udp_socket_get_ttl ()

    gint        gnet_udp_socket_get_ttl         (GUdpSocket *us);

Get the TTL of the UDP socket. TTL is the Time To Live - the number of hops outgoing packets will travel. This is useful for resource discovery; for most programs, you don't need to use it.

`us` : | GUdpSocket to get TTL from.
Returns : | the TTL; -1 on failure.

### gnet_udp_socket_set_ttl ()

    gint        gnet_udp_socket_set_ttl         (GUdpSocket *us,
                                                 int val);

Set the TTL of the UDP socket.

`us` : | GUdpSocket to set TTL.
`val` : | Value to set TTL to.
Returns : | 0 if successful.

### gnet_udp_socket_get_mcast_ttl ()

    gint        gnet_udp_socket_get_mcast_ttl   (GUdpSocket *us);

Get the TTL for outgoing multicast packests. TTL is the Time To Live - the number of hops outgoing packets will travel. The default TTL is usually 1, which mean outgoing packets will only travel as far as the local subnet.

This reason this function is in the UDP module is that UdpSocket's (as well as McastSocket's) can be used to sent to multicast groups.

Here's a handy table. Note that the "meaning" really doesn't mean anything. The mcast people basically just gave them these names because they sounded cool.

<table> <title>TTL and "meaning"</title> <tgroup cols=2 align=left> <thead> <row> <entry>TTL</entry> <entry>meaning</entry> </row> </thead> <tbody> <row> <entry>0</entry> <entry>node local</entry> </row> <row> <entry>1</entry> <entry>link local</entry> </row> <row> <entry>2-32</entry> <entry>site local</entry> </row> <row> <entry>33-64</entry> <entry>region local</entry> </row> <row> <entry>65-128</entry> <entry>continent local</entry> </row> <row> <entry>129-255</entry> <entry>unrestricted (global)</entry> </row> </tbody> </table>

`us` : | GUdpSocket to get TTL from.
Returns : | the TTL; -1 on failure.

### gnet_udp_socket_set_mcast_ttl ()

    gint        gnet_udp_socket_set_mcast_ttl   (GUdpSocket *us,
                                                 gint val);

Set the TTL for outgoing multicast packets.

This reason this function is in the UDP module is that UdpSocket's (as well as McastSocket's) can be used to sent to multicast groups.

`us` : | GUdpSocket to set mcast TTL.
`val` : | Value to set mcast TTL to.
Returns : | 0 if successful.

### gnet_udp_packet_receive_new ()

    GUdpPacket* gnet_udp_packet_receive_new     (gint8 *data,
                                                 gint length);

Create a packet for receiving.

`data` : | A pointer to the buffer to use for the received data.
`length` : | The length of this buffer.
Returns : | a new GUdpPacket.

### gnet_udp_packet_send_new ()

    GUdpPacket* gnet_udp_packet_send_new        (gint8 *data,
                                                 gint length,
                                                 GInetAddr *addr);

Create a packet for sending.

`data` : | A pointer to the buffer which contains the data to send.
`length` : | The length of this buffer.
`addr` : | The address to which the packet should be sent.
Returns : | a new GUdpPacket.

### gnet_udp_packet_delete ()

    void        gnet_udp_packet_delete          (GUdpPacket *packet);

Delete a UDP packet. The buffer is not deleted.

`packet` : | GUdpPacket to delete.

<<< Previous Page | Home | Up |
TCP module |