GNetworkDatagram

GNetworkDatagram — The interface for connectionless socket objects.

Synopsis




struct      GNetworkDatagram;
enum        GNetworkDatagramStatus;
void        gnetwork_datagram_open          (GNetworkDatagram *datagram);
void        gnetwork_datagram_close         (GNetworkDatagram *datagram);
void        gnetwork_datagram_send          (GNetworkDatagram *datagram,
                                             const GValue *destination,
                                             gconstpointer data,
                                             glong length);
struct      GNetworkDatagramIface;
void        gnetwork_datagram_received      (GNetworkDatagram *datagram,
                                             const GValue *source,
                                             gconstpointer data,
                                             gulong length);
void        gnetwork_datagram_sent          (GNetworkDatagram *datagram,
                                             const GValue *destination,
                                             gconstpointer data,
                                             gulong length);
void        gnetwork_datagram_error         (GNetworkDatagram *datagram,
                                             const GValue *info,
                                             const GError *error);
void        (*GNetworkDatagramFunc)         (GNetworkDatagram *datagram);
void        (*GNetworkDatagramSendFunc)     (GNetworkDatagram *datagram,
                                             const GValue *destination,
                                             gconstpointer data,
                                             glong length);
#define     GNETWORK_DATAGRAM_CALL_PARENT   (obj,method,args)

Object Hierarchy


  GInterface
   +----GNetworkDatagram

Prerequisites

GNetworkDatagram requires GObject.

Known Implementations

GNetworkDatagram is implemented by GNetworkUdpDatagram and GNetworkIpMulticast.

Properties


  "buffer-size"          guint                 : Read / Write / Construct
  "bytes-received"       gulong                : Read
  "bytes-sent"           gulong                : Read
  "status"               GNetworkDatagramStatus  : Read

Signal Prototypes


"error"     void        user_function      (GNetworkDatagram *gnetworkdatagram,
                                            GValue *arg1,
                                            GError *arg2,
                                            gpointer user_data);
"received"  void        user_function      (GNetworkDatagram *gnetworkdatagram,
                                            GValue *arg1,
                                            gpointer arg2,
                                            gulong arg3,
                                            gpointer user_data);
"sent"      void        user_function      (GNetworkDatagram *gnetworkdatagram,
                                            GValue *arg1,
                                            gpointer arg2,
                                            gulong arg3,
                                            gpointer user_data);

Description

The GNetworkDatagramIface provides a standard set of methods and signals for connectionless protocols, such as UDP (and IP Multicast) and the datagram version of the Unix IPC protocol.

Unlike connection-based protocols (such as TCP/IP or the Unix stream IPC protocol), datagram protocols have only one object, used both for sending to and receiving from any other datagram socket. This means that datagram sockets are not reliable, but they are faster and can be used to send and receive "broadcasts" (data sent willy-nilly to multiple destinations).

Implementations should note that because of the extensive use of implementation-specific GValue structures in GNetworkDatagramIface, subclasses may have to "chain up" using GNETWORK_DATAGRAM_CALL_PARENT. For example, imagine a subclass of GNetworkUdpDatagram which identifies destinations by a string. Since this subclass wants to override the GNetworkDatagramIface methods provided by GNetworkUdpDatagram, as well as make the GValue parameters hold strings, rather than GNetworkUdpTarget (the default for UDP datagrams), it needs to interrupt the normal flow and filter the data before continuing. Therefore, the "send" method would look something like this:

static void
my_object_dgram_send (GNetworkDatagram * dgram,
		      const GValue * destination,
		      gconstpointer data,
		      glong length)
{
  const gchar *info;
  GNetworkUdpTarget *target;
  GError *error;
  GValue udp_value = { 0 };

  if (destination != NULL)
    {
      info = g_value_get_string (destination);

      /* "Convert" to GNetworkUdpTarget before continuing up. */
      if (info != NULL)
	{
	  target = gnetwork_udp_target_new (get_host_for_info (info), THE_PORT);

	  g_value_init (&udp_value, GNETWORK_TYPE_UDP_TARGET);
	  g_value_take_boxed (&udp_value, target);

	  GNETWORK_DATAGRAM_CALL_PARENT (dgram, send,
					 (dgram, &udp_value, data, length));

	  g_value_unset (&udp_value);
	  return;
	}
    }

  /* In order to get here, either destination or info is NULL */
  error = g_error_new_literal (MY_ERROR_DOMAIN, MY_ERROR_BAD_DESTINATION,
			       "The destination name was blank");
  gnetwork_datagram_error (dgram, destination, error);
  g_error_free (error);
}

and, the "received" signal handler would look something like this (converting the GNetworkUdpTarget into a string ID):

static void
my_object_dgram_received (GNetworkDatagram * dgram,
			  GValue * source,
			  gconstpointer data,
			  gulong length)
{
  GNetworkUdpTarget *target;
  gchar *ipaddr;
  gchar *info;

  /* Guaranteed by GNetworkUdpDatagram */
  g_assert (source != NULL);

  target = g_value_get_boxed (source);

  /* Guaranteed by GNetworkUdpDatagram */
  g_assert (target != NULL);

  ipaddr = gnetwork_udp_target_get_host (target);

  info = get_info_for_host (host);
  g_free (host);

  g_value_reset (source);
  g_value_init (source, G_TYPE_STRING);
  g_value_take_string (source, info);
}

Details

struct GNetworkDatagram

struct GNetworkDatagram;

An empty typedef for GNetworkDatagramIface implementations.


enum GNetworkDatagramStatus

typedef enum /* <prefix=GNETWORK_DATAGRAM> */
{
  GNETWORK_DATAGRAM_CLOSING,
  GNETWORK_DATAGRAM_CLOSED,
  GNETWORK_DATAGRAM_OPENING,
  GNETWORK_DATAGRAM_OPEN
}
GNetworkDatagramStatus;

An enumeration of the possible states a GNetworkDatagramIface implementation may be in.

GNETWORK_DATAGRAM_CLOSINGthe object is shutting down.
GNETWORK_DATAGRAM_CLOSEDthe object is shut down.
GNETWORK_DATAGRAM_OPENINGthe object is opening.
GNETWORK_DATAGRAM_OPENthe object is ready to send/receive.

gnetwork_datagram_open ()

void        gnetwork_datagram_open          (GNetworkDatagram *datagram);

Starts the datagram process for datagram.

datagram : the datagram to open.

Since 1.0


gnetwork_datagram_close ()

void        gnetwork_datagram_close         (GNetworkDatagram *datagram);

Closes the datagram in question.

datagram : the datagram to close.

Since 1.0


gnetwork_datagram_send ()

void        gnetwork_datagram_send          (GNetworkDatagram *datagram,
                                             const GValue *destination,
                                             gconstpointer data,
                                             glong length);

Sends the data in data through datagram to destination. If length is less than zero, data is assumed to be terminated by 0, and the necessary calculations for length will be performed.

datagram : the datagram object to send through.
destination : implementation-specific destination information.
data : the data to send.
length : the length of data in bytes, or -1.

Since 1.0


struct GNetworkDatagramIface

struct GNetworkDatagramIface {

  /* Signals */
  void (*received)         (GNetworkDatagram * datagram,
			    GValue *source,
			    gconstpointer data,
			    gulong length);
  void (*sent)		   (GNetworkDatagram * datagram,
			    GValue *destination,
			    gconstpointer data,
			    gulong length);
  void (*error)		   (GNetworkDatagram * datagram,
			    GValue *info,
			    GError * error);

  /* Methods */
  GNetworkDatagramFunc      open;
  GNetworkDatagramFunc      close;
  GNetworkDatagramSendFunc  send;

};

The interface for connectionless sockets.

void (*received) (GNetworkDatagram * datagram, GValue *source, gconstpointer data, gulong length)the object callback slot for the "received" signal.
void (*sent) (GNetworkDatagram * datagram, GValue *destination, gconstpointer data, gulong length)the object callback slot for the "sent" signal.
void (*error) (GNetworkDatagram * datagram, GValue *info, GError * error)the object callback slot for the "error" signal.
GNetworkDatagramFunc opena method to open the socket.
GNetworkDatagramFunc closea method to close the socket.
GNetworkDatagramSendFunc senda method to send data via the socket.

gnetwork_datagram_received ()

void        gnetwork_datagram_received      (GNetworkDatagram *datagram,
                                             const GValue *source,
                                             gconstpointer data,
                                             gulong length);

Emits the "received" signal for datagram, using the values in source, data and length. Implementations of the GNetworkDatagramIface interface should use this function to emit the proper signal when data has been received.

datagram : the datagram to use.
source : implementation-specific information about the sender.
data : the data being recieved.
length : the length of data in bytes.

Since 1.0


gnetwork_datagram_sent ()

void        gnetwork_datagram_sent          (GNetworkDatagram *datagram,
                                             const GValue *destination,
                                             gconstpointer data,
                                             gulong length);

Emits the "sent" signal for datagram, using the values in source, data and length. Implementations of the GNetworkDatagramIface interface should use this function to emit the proper signal when data has been sent.

datagram : the datagram to use.
destination : implementation-specific information about the destination.
data : the data being recieved.
length : the length of data in bytes.

Since 1.0


gnetwork_datagram_error ()

void        gnetwork_datagram_error         (GNetworkDatagram *datagram,
                                             const GValue *info,
                                             const GError *error);

Emits the "error" signal for datagram, using info and error.

datagram : the datagram to use.
info : implementation-specific information about the target who caused the error.
error : the error structure.

Since 1.0


GNetworkDatagramFunc ()

void        (*GNetworkDatagramFunc)         (GNetworkDatagram *datagram);

A basic implementation function type for methods of the GNetworkDatagramIface interface.

datagram :the object in question.

GNetworkDatagramSendFunc ()

void        (*GNetworkDatagramSendFunc)     (GNetworkDatagram *datagram,
                                             const GValue *destination,
                                             gconstpointer data,
                                             glong length);

An implementation function type for the method which sends data.

datagram :the object in question.
destination :the encapsulated implementation-specific destination to send data to.
data :the data to send.
length :the length of data, in bytes.

GNETWORK_DATAGRAM_CALL_PARENT()

#define     GNETWORK_DATAGRAM_CALL_PARENT(obj,method,args)

A macro to call a parent class' GNetworkDatagramIface implementation of method. Typically, this would be used to "chain up" after overriding a method or signal callback.

obj :the object in question.
method :the method to call.
args :the arguments to pass the method.

Properties

The "buffer-size" property

  "buffer-size"          guint                 : Read / Write / Construct

The maximum size in bytes of outgoing and incoming data packets.

Default value: 2048


The "bytes-received" property

  "bytes-received"       gulong                : Read

The number of bytes received through this datagram socket.


The "bytes-sent" property

  "bytes-sent"           gulong                : Read

The number of bytes sent through this datagram socket.


The "status" property

  "status"               GNetworkDatagramStatus  : Read

The status of this datagram socket.

Default value: GNETWORK_DATAGRAM_CLOSED

Signals

The "error" signal

void        user_function                  (GNetworkDatagram *gnetworkdatagram,
                                            GValue *arg1,
                                            GError *arg2,
                                            gpointer user_data);

This signal is emitted when an error has occurred for the datagram object.

gnetworkdatagram :the object which received the signal.
arg1 :the encapsulated implementation-specific data for the destination or sender which caused the error.
arg2 :the error itself.
user_data :user data set when the signal handler was connected.

The "received" signal

void        user_function                  (GNetworkDatagram *gnetworkdatagram,
                                            GValue *arg1,
                                            gpointer arg2,
                                            gulong arg3,
                                            gpointer user_data);

This signal is emitted when data has been received from the datagram object.

gnetworkdatagram :the object which received the signal.
arg1 :the encapsulated implementation-specific data for the sender.
arg2 :the data received.
arg3 :the length of arg2 in bytes.
user_data :user data set when the signal handler was connected.

The "sent" signal

void        user_function                  (GNetworkDatagram *gnetworkdatagram,
                                            GValue *arg1,
                                            gpointer arg2,
                                            gulong arg3,
                                            gpointer user_data);

This signal is emitted when data has been sucessfully sent via the datagram object.

gnetworkdatagram :the object which received the signal.
arg1 :the encapsulated implementation-specific data for the destination.
arg2 :the data received.
arg3 :the length of arg2 in bytes.
user_data :user data set when the signal handler was connected.