GNOME.org

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.