### Interface

# Gio DatagramBased

since: 2.48

#### Description [src]

    interface Gio.DatagramBased : GObject.Object

Interface for socket-like objects with datagram semantics.

A `GDatagramBased` is a networking interface for representing datagram-based communications. It is a more or less direct mapping of the core parts of the BSD socket API in a portable GObject interface. It is implemented by `GSocket`, which wraps the UNIX socket API on UNIX and winsock2 on Windows.

`GDatagramBased` is entirely platform independent, and is intended to be used alongside higher-level networking APIs such as `GIOStream`.

It uses vectored scatter/gather I/O by default, allowing for many messages to be sent or received in a single call. Where possible, implementations of the interface should take advantage of vectored I/O to minimise processing or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()` where possible. Callers should take advantage of scatter/gather I/O (the use of multiple buffers per message) to avoid unnecessary copying of data to assemble or disassemble a message.

Each `GDatagramBased` operation has a timeout parameter which may be negative for blocking behaviour, zero for non-blocking behaviour, or positive for timeout behaviour. A blocking operation blocks until finished or there is an error. A non-blocking operation will return immediately with a `G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation will block until the operation is complete or the timeout expires; if the timeout expires it will return what progress it made, or `G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would successfully run you can call `g_datagram_based_condition_check()` or `g_datagram_based_condition_wait()`. You can also use `g_datagram_based_create_source()` and attach it to a `GMainContext` to get callbacks when I/O is possible.

When running a non-blocking operation applications should always be able to handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write returns `G_IO_ERROR_WOULD_BLOCK`.

As with `GSocket`, `GDatagramBased`s can be either connection oriented (for example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be datagram-based, not stream-based. The interface does not cover connection establishment — use methods on the underlying type to establish a connection before sending and receiving data through the `GDatagramBased` API. For connectionless socket types the target/source address is specified or received in each I/O operation.

Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe. To use a `GDatagramBased` concurrently from multiple threads, you must implement your own locking.

Available since: 2.48

#### Prerequisite

In order to implement DatagramBased, your type must inherit from`GObject`.

#### Implementations

- GSocket

#### Instance methods

###### g_datagram_based_condition_check

Checks on the readiness of `datagram_based` to perform operations. The operations specified in `condition` are checked for and masked against the currently-satisfied conditions on `datagram_based`. The result is returned.

since: 2.48

###### g_datagram_based_condition_wait

Waits for up to `timeout` microseconds for condition to become true on `datagram_based`. If the condition is met, `TRUE` is returned.

since: 2.48

###### g_datagram_based_create_source

Creates a `GSource` that can be attached to a `GMainContext` to monitor for the availability of the specified `condition` on the `GDatagramBased`. The `GSource` keeps a reference to the `datagram_based`.

since: 2.48

###### g_datagram_based_receive_messages

Receive one or more data messages from `datagram_based` in one go.

since: 2.48

###### g_datagram_based_send_messages

Send one or more data messages from `datagram_based` in one go.

since: 2.48

#### Interface structure

    struct GioDatagramBasedInterface {
      GTypeInterface g_iface;
      gint (* receive_messages) (
        GDatagramBased* datagram_based,
        GInputMessage* messages,
        guint num_messages,
        gint flags,
        gint64 timeout,
        GCancellable* cancellable,
        GError** error
      );
      gint (* send_messages) (
        GDatagramBased* datagram_based,
        GOutputMessage* messages,
        guint num_messages,
        gint flags,
        gint64 timeout,
        GCancellable* cancellable,
        GError** error
      );
      GSource* (* create_source) (
        GDatagramBased* datagram_based,
        GIOCondition condition,
        GCancellable* cancellable
      );
      GIOCondition (* condition_check) (
        GDatagramBased* datagram_based,
        GIOCondition condition
      );
      gboolean (* condition_wait) (
        GDatagramBased* datagram_based,
        GIOCondition condition,
        gint64 timeout,
        GCancellable* cancellable,
        GError** error
      );

    }

Provides an interface for socket-like objects which have datagram semantics, following the Berkeley sockets API. The interface methods are thin wrappers around the corresponding virtual methods, and no pre-processing of inputs is implemented — so implementations of this API must handle all functionality documented in the interface methods.

###### Interface members

`g_iface` |
    GTypeInterface
| The parent interface.
`receive_messages` |
    gint (* receive_messages) (
        GDatagramBased* datagram_based,
        GInputMessage* messages,
        guint num_messages,
        gint flags,
        gint64 timeout,
        GCancellable* cancellable,
        GError** error
      )
| Virtual method for g_datagram_based_receive_messages().
`send_messages` |
    gint (* send_messages) (
        GDatagramBased* datagram_based,
        GOutputMessage* messages,
        guint num_messages,
        gint flags,
        gint64 timeout,
        GCancellable* cancellable,
        GError** error
      )
| Virtual method for g_datagram_based_send_messages().
`create_source` |
    GSource* (* create_source) (
        GDatagramBased* datagram_based,
        GIOCondition condition,
        GCancellable* cancellable
      )
| Virtual method for g_datagram_based_create_source().
`condition_check` |
    GIOCondition (* condition_check) (
        GDatagramBased* datagram_based,
        GIOCondition condition
      )
| Virtual method for g_datagram_based_condition_check().
`condition_wait` |
    gboolean (* condition_wait) (
        GDatagramBased* datagram_based,
        GIOCondition condition,
        gint64 timeout,
        GCancellable* cancellable,
        GError** error
      )
| Virtual method for g_datagram_based_condition_wait().

#### Virtual methods

###### Gio.DatagramBased.condition_check

Checks on the readiness of `datagram_based` to perform operations. The operations specified in `condition` are checked for and masked against the currently-satisfied conditions on `datagram_based`. The result is returned.

since: 2.48

###### Gio.DatagramBased.condition_wait

Waits for up to `timeout` microseconds for condition to become true on `datagram_based`. If the condition is met, `TRUE` is returned.

since: 2.48

###### Gio.DatagramBased.create_source

Creates a `GSource` that can be attached to a `GMainContext` to monitor for the availability of the specified `condition` on the `GDatagramBased`. The `GSource` keeps a reference to the `datagram_based`.

since: 2.48

###### Gio.DatagramBased.receive_messages

Receive one or more data messages from `datagram_based` in one go.

since: 2.48

###### Gio.DatagramBased.send_messages

Send one or more data messages from `datagram_based` in one go.

since: 2.48