GNet Network Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# udp

## Name

udp --

## Synopsis

    struct      GUdpSocket;
    struct      GUdpPacket;
    GUdpSocket* gnet_udp_socket_new             (void);
    GUdpSocket* gnet_udp_socket_port_new        (gint port);
    GUdpSocket* gnet_udp_socket_new_interface   (const GInetAddr *iface);
    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            (GUdpSocket *s,
                                                 const GUdpPacket *packet);
    gint        gnet_udp_socket_receive         (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         (const GUdpSocket *us);
    gint        gnet_udp_socket_set_ttl         (GUdpSocket *us,
                                                 int val);
    gint        gnet_udp_socket_get_mcast_ttl   (const GUdpSocket *us);
    gint        gnet_udp_socket_set_mcast_ttl   (GUdpSocket *us,
                                                 gint val);
    GUdpPacket* gnet_udp_packet_receive_new     (guint8 *data,
                                                 gint length);
    GUdpPacket* gnet_udp_packet_send_new        (guint8 *data,
                                                 gint length,
                                                 GInetAddr *addr);
    void        gnet_udp_packet_delete          (GUdpPacket *packet);

## Description

## Details

### struct GUdpSocket

    struct GUdpSocket;

### struct GUdpPacket

    struct GUdpPacket
    {
      gint8* data;
      guint length;

      GInetAddr* addr;

    };

GUdpPacket is a simple helper struct. Its fields are public. The fields 'data' and 'addr' must be deallocated by the programmer if necessary when appropriate.

### gnet_udp_socket_new ()

    GUdpSocket* gnet_udp_socket_new             (void);

Create and open a new UDP socket with any port.

Returns : |

### gnet_udp_socket_port_new ()

    GUdpSocket* gnet_udp_socket_port_new        (gint port);

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

`port` : |
Returns : |

### gnet_udp_socket_new_interface ()

    GUdpSocket* gnet_udp_socket_new_interface   (const GInetAddr *iface);

Create and open a new UDP socket bound to the specified interface. If the interface address's port number is 0, the OS will choose the port.

`iface` : |
Returns : |

### gnet_udp_socket_delete ()

    void        gnet_udp_socket_delete          (GUdpSocket *s);

Close and delete a UDP socket.

`s` : |

### gnet_udp_socket_ref ()

    void        gnet_udp_socket_ref             (GUdpSocket *s);

Increment the reference counter of the GUdpSocket.

`s` : |

### 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` : |

### gnet_udp_socket_send ()

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

Send the packet using the GUdpSocket.

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

### gnet_udp_socket_receive ()

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

Receive a packet using the UDP socket.

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

### 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` : |
Returns : |

### 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 asynchronous IO (so if you do not want to do asynchronous 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` : |
Returns : |

### gnet_udp_socket_get_ttl ()

    gint        gnet_udp_socket_get_ttl         (const 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` : |
Returns : |

### gnet_udp_socket_set_ttl ()

    gint        gnet_udp_socket_set_ttl         (GUdpSocket *us,
                                                 int val);

Set the TTL of the UDP socket.

`us` : |
`val` : |
Returns : |

### gnet_udp_socket_get_mcast_ttl ()

    gint        gnet_udp_socket_get_mcast_ttl   (const 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` : |
Returns : |

### 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` : |
`val` : |
Returns : |

### gnet_udp_packet_receive_new ()

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

Create a packet for receiving. `data` is a shallow copy and must be deallocated by the caller if necessary when appropriate.

`data` : |
`length` : |
Returns : |

### gnet_udp_packet_send_new ()

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

Create a packet for sending. The fields of the new packet are public. `data` and `addr` are shallow copies and must be deallocated by the caller if necessary when appropriate.

`data` : |
`length` : |
`addr` : |
Returns : |

### gnet_udp_packet_delete ()

    void        gnet_udp_packet_delete          (GUdpPacket *packet);

Delete a UDP packet. The fields "data" and "addr" are not deleted and should be deallocated by the programmer if necessary when appropriate.

`packet` : |

<<< Previous Page | Home | Up | Next Page >>>
socks | mcast