gio/gdatagrambased.c - third_party/glib - Git at Google

 /* GIO - GLib Input, Output and Streaming Library
  *
  * Copyright 2015 Collabora Ltd.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
  * version 2.1 of the License, or (at your option) any later version.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General
  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  *
  * Authors: Philip Withnall <philip.withnall@collabora.co.uk>
  */

 #include "config.h"

 #include "gdatagrambased.h"

 #include "gcancellable.h"
 #include "gioenumtypes.h"
 #include "gioerror.h"
 #include "gnetworkingprivate.h"
 #include "gsocketaddress.h"
 #include "glibintl.h"

 /**
  * SECTION:gdatagrambased
  * @short_description: Low-level datagram communications interface
  * @include: gio/gio.h
  * @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h]
  *
  * 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, #GDatagramBaseds can be either connection oriented (for
  * example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds 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.
  *
  * Since: 2.48
  */

 G_DEFINE_INTERFACE (GDatagramBased, g_datagram_based, G_TYPE_OBJECT)

 static void
 g_datagram_based_default_init (GDatagramBasedInterface *iface)
 {
   /* Nothing here. */
 }

 /**
  * g_datagram_based_receive_messages:
  * @datagram_based: a #GDatagramBased
  * @messages: (array length=num_messages): an array of #GInputMessage structs
  * @num_messages: the number of elements in @messages
  * @flags: an int containing #GSocketMsgFlags flags for the overall operation
  * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
  *   to block indefinitely
  * @cancellable: (nullable): a %GCancellable
  * @error: return location for a #GError
  *
  * Receive one or more data messages from @datagram_based in one go.
  *
  * @messages must point to an array of #GInputMessage structs and
  * @num_messages must be the length of this array. Each #GInputMessage
  * contains a pointer to an array of #GInputVector structs describing the
  * buffers that the data received in each message will be written to.
  *
  * @flags modify how all messages are received. The commonly available
  * arguments for this are available in the #GSocketMsgFlags enum, but the
  * values there are the same as the system values, and the flags
  * are passed in as-is, so you can pass in system-specific flags too. These
  * flags affect the overall receive operation. Flags affecting individual
  * messages are returned in #GInputMessage.flags.
  *
  * The other members of #GInputMessage are treated as described in its
  * documentation.
  *
  * If @timeout is negative the call will block until @num_messages have been
  * received, the connection is closed remotely (EOS), @cancellable is cancelled,
  * or an error occurs.
  *
  * If @timeout is 0 the call will return up to @num_messages without blocking,
  * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
  * to be received.
  *
  * If @timeout is positive the call will block on the same conditions as if
  * @timeout were negative. If the timeout is reached
  * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
  * otherwise it will return the number of messages received before timing out.
  * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with
  * recvmmsg().)
  *
  * To be notified when messages are available, wait for the %G_IO_IN condition.
  * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
  * g_datagram_based_receive_messages() even if you were previously notified of a
  * %G_IO_IN condition.
  *
  * If the remote peer closes the connection, any messages queued in the
  * underlying receive buffer will be returned, and subsequent calls to
  * g_datagram_based_receive_messages() will return 0 (with no error set).
  *
  * If the connection is shut down or closed (by calling g_socket_close() or
  * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
  * example), all calls to this function will return %G_IO_ERROR_CLOSED.
  *
  * On error -1 is returned and @error is set accordingly. An error will only
  * be returned if zero messages could be received; otherwise the number of
  * messages successfully received before the error will be returned. If
  * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
  * other error.
  *
  * Returns: number of messages received, or -1 on error. Note that the number
  *     of messages received may be smaller than @num_messages if @timeout is
  *     zero or positive, if the peer closed the connection, or if @num_messages
  *     was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
  *     to receive the remaining messages.
  *
  * Since: 2.48
  */
 gint
 g_datagram_based_receive_messages (GDatagramBased  *datagram_based,
                                    GInputMessage   *messages,
                                    guint            num_messages,
                                    gint             flags,
                                    gint64           timeout,
                                    GCancellable    *cancellable,
                                    GError         **error)
 {
   GDatagramBasedInterface *iface;
   gint retval;
   GError *child_error = NULL;

   g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), -1);
   g_return_val_if_fail (num_messages == 0 || messages != NULL, -1);
   g_return_val_if_fail (cancellable == NULL ||
                         G_IS_CANCELLABLE (cancellable), -1);
   g_return_val_if_fail (error == NULL || *error == NULL, -1);

   iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
   g_assert (iface->receive_messages != NULL);

   retval = iface->receive_messages (datagram_based, messages, num_messages,
                                     flags, timeout, cancellable, &child_error);

   /* Postconditions. */
   g_return_val_if_fail ((retval < 0) == (child_error != NULL), -1);
   g_return_val_if_fail (timeout == 0 ||
                         !g_error_matches (child_error, G_IO_ERROR,
                                           G_IO_ERROR_WOULD_BLOCK), -1);
   g_return_val_if_fail (timeout > 0 ||
                         !g_error_matches (child_error, G_IO_ERROR,
                                           G_IO_ERROR_TIMED_OUT), -1);
   g_return_val_if_fail (retval < 0 || (guint) retval <= num_messages, -1);

   if (child_error != NULL)
       g_propagate_error (error, child_error);

   return retval;
 }

 /**
  * g_datagram_based_send_messages:
  * @datagram_based: a #GDatagramBased
  * @messages: (array length=num_messages): an array of #GOutputMessage structs
  * @num_messages: the number of elements in @messages
  * @flags: an int containing #GSocketMsgFlags flags
  * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
  *   to block indefinitely
  * @cancellable: (nullable): a %GCancellable
  * @error: return location for a #GError
  *
  * Send one or more data messages from @datagram_based in one go.
  *
  * @messages must point to an array of #GOutputMessage structs and
  * @num_messages must be the length of this array. Each #GOutputMessage
  * contains an address to send the data to, and a pointer to an array of
  * #GOutputVector structs to describe the buffers that the data to be sent
  * for each message will be gathered from.
  *
  * @flags modify how the message is sent. The commonly available arguments
  * for this are available in the #GSocketMsgFlags enum, but the
  * values there are the same as the system values, and the flags
  * are passed in as-is, so you can pass in system-specific flags too.
  *
  * The other members of #GOutputMessage are treated as described in its
  * documentation.
  *
  * If @timeout is negative the call will block until @num_messages have been
  * sent, @cancellable is cancelled, or an error occurs.
  *
  * If @timeout is 0 the call will send up to @num_messages without blocking,
  * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
  *
  * If @timeout is positive the call will block on the same conditions as if
  * @timeout were negative. If the timeout is reached before any messages are
  * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
  * of messages sent before timing out.
  *
  * To be notified when messages can be sent, wait for the %G_IO_OUT condition.
  * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
  * g_datagram_based_send_messages() even if you were previously notified of a
  * %G_IO_OUT condition. (On Windows in particular, this is very common due to
  * the way the underlying APIs work.)
  *
  * If the connection is shut down or closed (by calling g_socket_close() or
  * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for
  * example), all calls to this function will return %G_IO_ERROR_CLOSED.
  *
  * On error -1 is returned and @error is set accordingly. An error will only
  * be returned if zero messages could be sent; otherwise the number of messages
  * successfully sent before the error will be returned. If @cancellable is
  * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
  *
  * Returns: number of messages sent, or -1 on error. Note that the number of
  *     messages sent may be smaller than @num_messages if @timeout is zero
  *     or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
  *     which case the caller may re-try to send the remaining messages.
  *
  * Since: 2.48
  */
 gint
 g_datagram_based_send_messages (GDatagramBased   *datagram_based,
                                 GOutputMessage   *messages,
                                 guint             num_messages,
                                 gint              flags,
                                 gint64            timeout,
                                 GCancellable     *cancellable,
                                 GError          **error)
 {
   GDatagramBasedInterface *iface;
   gint retval;
   GError *child_error = NULL;

   g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), -1);
   g_return_val_if_fail (num_messages == 0 || messages != NULL, -1);
   g_return_val_if_fail (cancellable == NULL ||
                         G_IS_CANCELLABLE (cancellable), -1);
   g_return_val_if_fail (error == NULL || *error == NULL, -1);

   iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
   g_assert (iface->send_messages != NULL);

   retval = iface->send_messages (datagram_based, messages, num_messages, flags,
                                  timeout, cancellable, &child_error);

   /* Postconditions. */
   g_return_val_if_fail ((retval < 0) == (child_error != NULL), -1);
   g_return_val_if_fail (timeout == 0 ||
                         !g_error_matches (child_error, G_IO_ERROR,
                                           G_IO_ERROR_WOULD_BLOCK), -1);
   g_return_val_if_fail (timeout > 0 ||
                         !g_error_matches (child_error, G_IO_ERROR,
                                           G_IO_ERROR_TIMED_OUT), -1);
   g_return_val_if_fail (retval < 0 || (guint) retval <= num_messages, -1);
   g_return_val_if_fail (!(timeout < 0 && num_messages > 0) || retval != 0, -1);

   if (child_error != NULL)
       g_propagate_error (error, child_error);

   return retval;
 }

 /**
  * g_datagram_based_create_source:
  * @datagram_based: a #GDatagramBased
  * @condition: a #GIOCondition mask to monitor
  * @cancellable: (nullable): a #GCancellable
  *
  * 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.
  *
  * The callback on the source is of the #GDatagramBasedSourceFunc type.
  *
  * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
  * conditions will always be reported in the callback if they are true.
  *
  * If non-%NULL, @cancellable can be used to cancel the source, which will
  * cause the source to trigger, reporting the current condition (which is
  * likely 0 unless cancellation happened at the same time as a condition
  * change). You can check for this in the callback using
  * g_cancellable_is_cancelled().
  *
  * Returns: (transfer full): a newly allocated #GSource
  *
  * Since: 2.48
  */
 GSource *
 g_datagram_based_create_source (GDatagramBased *datagram_based,
                                 GIOCondition    condition,
                                 GCancellable   *cancellable)
 {
   GDatagramBasedInterface *iface;

   g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), NULL);
   g_return_val_if_fail (cancellable == NULL ||
                         G_IS_CANCELLABLE (cancellable), NULL);

   iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
   g_assert (iface->create_source != NULL);

   return iface->create_source (datagram_based, condition, cancellable);
 }

 /**
  * g_datagram_based_condition_check:
  * @datagram_based: a #GDatagramBased
  * @condition: a #GIOCondition mask to 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.
  *
  * %G_IO_IN will be set in the return value if data is available to read with
  * g_datagram_based_receive_messages(), or if the connection is closed remotely
  * (EOS); and if the datagram_based has not been closed locally using some
  * implementation-specific method (such as g_socket_close() or
  * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
  *
  * If the connection is shut down or closed (by calling g_socket_close() or
  * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
  * example), all calls to this function will return %G_IO_ERROR_CLOSED.
  *
  * %G_IO_OUT will be set if it is expected that at least one byte can be sent
  * using g_datagram_based_send_messages() without blocking. It will not be set
  * if the datagram_based has been closed locally.
  *
  * %G_IO_HUP will be set if the connection has been closed locally.
  *
  * %G_IO_ERR will be set if there was an asynchronous error in transmitting data
  * previously enqueued using g_datagram_based_send_messages().
  *
  * Note that on Windows, it is possible for an operation to return
  * %G_IO_ERROR_WOULD_BLOCK even immediately after
  * g_datagram_based_condition_check() has claimed that the #GDatagramBased is
  * ready for writing. Rather than calling g_datagram_based_condition_check() and
  * then writing to the #GDatagramBased if it succeeds, it is generally better to
  * simply try writing right away, and try again later if the initial attempt
  * returns %G_IO_ERROR_WOULD_BLOCK.
  *
  * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
  * conditions will always be set in the output if they are true. Apart from
  * these flags, the output is guaranteed to be masked by @condition.
  *
  * This call never blocks.
  *
  * Returns: the #GIOCondition mask of the current state
  *
  * Since: 2.48
  */
 GIOCondition
 g_datagram_based_condition_check (GDatagramBased *datagram_based,
                                   GIOCondition    condition)
 {
   GDatagramBasedInterface *iface;
   GIOCondition out;

   g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), 0);

   iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
   g_assert (iface->condition_check != NULL);

   out = iface->condition_check (datagram_based, condition);

   /* Postconditions. G_IO_OUT and G_IO_HUP are mutually exclusive. G_IO_IN and
    * G_IO_HUP are mutually exclusive. The return value must be a subset of
    * (condition | G_IO_ERR | G_IO_HUP). */
   g_return_val_if_fail ((out & (G_IO_OUT | G_IO_HUP)) != (G_IO_OUT | G_IO_HUP),
                         out & ~G_IO_OUT);
   g_return_val_if_fail ((out & (G_IO_IN | G_IO_HUP)) != (G_IO_IN | G_IO_HUP),
                         out & ~G_IO_IN);
   g_return_val_if_fail ((out & ~(condition | G_IO_ERR | G_IO_HUP)) == 0,
                         out & (condition | G_IO_ERR | G_IO_HUP));

   return out;
 }

 /**
  * g_datagram_based_condition_wait:
  * @datagram_based: a #GDatagramBased
  * @condition: a #GIOCondition mask to wait for
  * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
  *   to block indefinitely
  * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError
  *
  * Waits for up to @timeout microseconds for condition to become true on
  * @datagram_based. If the condition is met, %TRUE is returned.
  *
  * If @cancellable is cancelled before the condition is met, or if @timeout is
  * reached before the condition is met, then %FALSE is returned and @error is
  * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
  *
  * Returns: %TRUE if the condition was met, %FALSE otherwise
  *
  * Since: 2.48
  */
 gboolean
 g_datagram_based_condition_wait (GDatagramBased  *datagram_based,
                                  GIOCondition     condition,
                                  gint64           timeout,
                                  GCancellable    *cancellable,
                                  GError         **error)
 {
   GDatagramBasedInterface *iface;
   gboolean out;
   GError *child_error = NULL;

   g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), FALSE);
   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
                         FALSE);
   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);

   iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
   g_assert (iface->condition_wait != NULL);

   out = iface->condition_wait (datagram_based, condition, timeout,
                                cancellable, &child_error);

   /* Postconditions. */
   g_return_val_if_fail (out == (child_error == NULL), FALSE);

   if (child_error != NULL)
     g_propagate_error (error, child_error);

   return out;
 }
	/* GIO - GLib Input, Output and Streaming Library
	*
	* Copyright 2015 Collabora Ltd.
	*
	* This library is free software; you can redistribute it and/or
	* modify it under the terms of the GNU Lesser General Public
	* License as published by the Free Software Foundation; either
	* version 2.1 of the License, or (at your option) any later version.
	*
	* This library is distributed in the hope that it will be useful,
	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	* Lesser General Public License for more details.
	*
	* You should have received a copy of the GNU Lesser General
	* Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
	*
	* Authors: Philip Withnall <philip.withnall@collabora.co.uk>
	*/

	#include "config.h"

	#include "gdatagrambased.h"

	#include "gcancellable.h"
	#include "gioenumtypes.h"
	#include "gioerror.h"
	#include "gnetworkingprivate.h"
	#include "gsocketaddress.h"
	#include "glibintl.h"

	/**
	* SECTION:gdatagrambased
	* @short_description: Low-level datagram communications interface
	* @include: gio/gio.h
	* @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h]
	*
	* 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, #GDatagramBaseds can be either connection oriented (for
	* example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds 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.
	*
	* Since: 2.48
	*/

	G_DEFINE_INTERFACE (GDatagramBased, g_datagram_based, G_TYPE_OBJECT)

	static void
	g_datagram_based_default_init (GDatagramBasedInterface *iface)
	{
	/* Nothing here. */
	}

	/**
	* g_datagram_based_receive_messages:
	* @datagram_based: a #GDatagramBased
	* @messages: (array length=num_messages): an array of #GInputMessage structs
	* @num_messages: the number of elements in @messages
	* @flags: an int containing #GSocketMsgFlags flags for the overall operation
	* @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
	* to block indefinitely
	* @cancellable: (nullable): a %GCancellable
	* @error: return location for a #GError
	*
	* Receive one or more data messages from @datagram_based in one go.
	*
	* @messages must point to an array of #GInputMessage structs and
	* @num_messages must be the length of this array. Each #GInputMessage
	* contains a pointer to an array of #GInputVector structs describing the
	* buffers that the data received in each message will be written to.
	*
	* @flags modify how all messages are received. The commonly available
	* arguments for this are available in the #GSocketMsgFlags enum, but the
	* values there are the same as the system values, and the flags
	* are passed in as-is, so you can pass in system-specific flags too. These
	* flags affect the overall receive operation. Flags affecting individual
	* messages are returned in #GInputMessage.flags.
	*
	* The other members of #GInputMessage are treated as described in its
	* documentation.
	*
	* If @timeout is negative the call will block until @num_messages have been
	* received, the connection is closed remotely (EOS), @cancellable is cancelled,
	* or an error occurs.
	*
	* If @timeout is 0 the call will return up to @num_messages without blocking,
	* or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
	* to be received.
	*
	* If @timeout is positive the call will block on the same conditions as if
	* @timeout were negative. If the timeout is reached
	* before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
	* otherwise it will return the number of messages received before timing out.
	* (Note: This is effectively the behaviour of `MSG_WAITFORONE` with
	* recvmmsg().)
	*
	* To be notified when messages are available, wait for the %G_IO_IN condition.
	* Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
	* g_datagram_based_receive_messages() even if you were previously notified of a
	* %G_IO_IN condition.
	*
	* If the remote peer closes the connection, any messages queued in the
	* underlying receive buffer will be returned, and subsequent calls to
	* g_datagram_based_receive_messages() will return 0 (with no error set).
	*
	* If the connection is shut down or closed (by calling g_socket_close() or
	* g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
	* example), all calls to this function will return %G_IO_ERROR_CLOSED.
	*
	* On error -1 is returned and @error is set accordingly. An error will only
	* be returned if zero messages could be received; otherwise the number of
	* messages successfully received before the error will be returned. If
	* @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
	* other error.
	*
	* Returns: number of messages received, or -1 on error. Note that the number
	* of messages received may be smaller than @num_messages if @timeout is
	* zero or positive, if the peer closed the connection, or if @num_messages
	* was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
	* to receive the remaining messages.
	*
	* Since: 2.48
	*/
	gint
	g_datagram_based_receive_messages (GDatagramBased *datagram_based,
	GInputMessage *messages,
	guint num_messages,
	gint flags,
	gint64 timeout,
	GCancellable *cancellable,
	GError **error)
	{
	GDatagramBasedInterface *iface;
	gint retval;
	GError *child_error = NULL;

	g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), -1);
	g_return_val_if_fail (num_messages == 0 \|\| messages != NULL, -1);
	g_return_val_if_fail (cancellable == NULL \|\|
	G_IS_CANCELLABLE (cancellable), -1);
	g_return_val_if_fail (error == NULL \|\| *error == NULL, -1);

	iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
	g_assert (iface->receive_messages != NULL);

	retval = iface->receive_messages (datagram_based, messages, num_messages,
	flags, timeout, cancellable, &child_error);

	/* Postconditions. */
	g_return_val_if_fail ((retval < 0) == (child_error != NULL), -1);
	g_return_val_if_fail (timeout == 0 \|\|
	!g_error_matches (child_error, G_IO_ERROR,
	G_IO_ERROR_WOULD_BLOCK), -1);
	g_return_val_if_fail (timeout > 0 \|\|
	!g_error_matches (child_error, G_IO_ERROR,
	G_IO_ERROR_TIMED_OUT), -1);
	g_return_val_if_fail (retval < 0 \|\| (guint) retval <= num_messages, -1);

	if (child_error != NULL)
	g_propagate_error (error, child_error);

	return retval;
	}

	/**
	* g_datagram_based_send_messages:
	* @datagram_based: a #GDatagramBased
	* @messages: (array length=num_messages): an array of #GOutputMessage structs
	* @num_messages: the number of elements in @messages
	* @flags: an int containing #GSocketMsgFlags flags
	* @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
	* to block indefinitely
	* @cancellable: (nullable): a %GCancellable
	* @error: return location for a #GError
	*
	* Send one or more data messages from @datagram_based in one go.
	*
	* @messages must point to an array of #GOutputMessage structs and
	* @num_messages must be the length of this array. Each #GOutputMessage
	* contains an address to send the data to, and a pointer to an array of
	* #GOutputVector structs to describe the buffers that the data to be sent
	* for each message will be gathered from.
	*
	* @flags modify how the message is sent. The commonly available arguments
	* for this are available in the #GSocketMsgFlags enum, but the
	* values there are the same as the system values, and the flags
	* are passed in as-is, so you can pass in system-specific flags too.
	*
	* The other members of #GOutputMessage are treated as described in its
	* documentation.
	*
	* If @timeout is negative the call will block until @num_messages have been
	* sent, @cancellable is cancelled, or an error occurs.
	*
	* If @timeout is 0 the call will send up to @num_messages without blocking,
	* or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
	*
	* If @timeout is positive the call will block on the same conditions as if
	* @timeout were negative. If the timeout is reached before any messages are
	* sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
	* of messages sent before timing out.
	*
	* To be notified when messages can be sent, wait for the %G_IO_OUT condition.
	* Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
	* g_datagram_based_send_messages() even if you were previously notified of a
	* %G_IO_OUT condition. (On Windows in particular, this is very common due to
	* the way the underlying APIs work.)
	*
	* If the connection is shut down or closed (by calling g_socket_close() or
	* g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for
	* example), all calls to this function will return %G_IO_ERROR_CLOSED.
	*
	* On error -1 is returned and @error is set accordingly. An error will only
	* be returned if zero messages could be sent; otherwise the number of messages
	* successfully sent before the error will be returned. If @cancellable is
	* cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
	*
	* Returns: number of messages sent, or -1 on error. Note that the number of
	* messages sent may be smaller than @num_messages if @timeout is zero
	* or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
	* which case the caller may re-try to send the remaining messages.
	*
	* Since: 2.48
	*/
	gint
	g_datagram_based_send_messages (GDatagramBased *datagram_based,
	GOutputMessage *messages,
	guint num_messages,
	gint flags,
	gint64 timeout,
	GCancellable *cancellable,
	GError **error)
	{
	GDatagramBasedInterface *iface;
	gint retval;
	GError *child_error = NULL;

	g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), -1);
	g_return_val_if_fail (num_messages == 0 \|\| messages != NULL, -1);
	g_return_val_if_fail (cancellable == NULL \|\|
	G_IS_CANCELLABLE (cancellable), -1);
	g_return_val_if_fail (error == NULL \|\| *error == NULL, -1);

	iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
	g_assert (iface->send_messages != NULL);

	retval = iface->send_messages (datagram_based, messages, num_messages, flags,
	timeout, cancellable, &child_error);

	/* Postconditions. */
	g_return_val_if_fail ((retval < 0) == (child_error != NULL), -1);
	g_return_val_if_fail (timeout == 0 \|\|
	!g_error_matches (child_error, G_IO_ERROR,
	G_IO_ERROR_WOULD_BLOCK), -1);
	g_return_val_if_fail (timeout > 0 \|\|
	!g_error_matches (child_error, G_IO_ERROR,
	G_IO_ERROR_TIMED_OUT), -1);
	g_return_val_if_fail (retval < 0 \|\| (guint) retval <= num_messages, -1);
	g_return_val_if_fail (!(timeout < 0 && num_messages > 0) \|\| retval != 0, -1);

	if (child_error != NULL)
	g_propagate_error (error, child_error);

	return retval;
	}

	/**
	* g_datagram_based_create_source:
	* @datagram_based: a #GDatagramBased
	* @condition: a #GIOCondition mask to monitor
	* @cancellable: (nullable): a #GCancellable
	*
	* 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.
	*
	* The callback on the source is of the #GDatagramBasedSourceFunc type.
	*
	* It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
	* conditions will always be reported in the callback if they are true.
	*
	* If non-%NULL, @cancellable can be used to cancel the source, which will
	* cause the source to trigger, reporting the current condition (which is
	* likely 0 unless cancellation happened at the same time as a condition
	* change). You can check for this in the callback using
	* g_cancellable_is_cancelled().
	*
	* Returns: (transfer full): a newly allocated #GSource
	*
	* Since: 2.48
	*/
	GSource *
	g_datagram_based_create_source (GDatagramBased *datagram_based,
	GIOCondition condition,
	GCancellable *cancellable)
	{
	GDatagramBasedInterface *iface;

	g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), NULL);
	g_return_val_if_fail (cancellable == NULL \|\|
	G_IS_CANCELLABLE (cancellable), NULL);

	iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
	g_assert (iface->create_source != NULL);

	return iface->create_source (datagram_based, condition, cancellable);
	}

	/**
	* g_datagram_based_condition_check:
	* @datagram_based: a #GDatagramBased
	* @condition: a #GIOCondition mask to 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.
	*
	* %G_IO_IN will be set in the return value if data is available to read with
	* g_datagram_based_receive_messages(), or if the connection is closed remotely
	* (EOS); and if the datagram_based has not been closed locally using some
	* implementation-specific method (such as g_socket_close() or
	* g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
	*
	* If the connection is shut down or closed (by calling g_socket_close() or
	* g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
	* example), all calls to this function will return %G_IO_ERROR_CLOSED.
	*
	* %G_IO_OUT will be set if it is expected that at least one byte can be sent
	* using g_datagram_based_send_messages() without blocking. It will not be set
	* if the datagram_based has been closed locally.
	*
	* %G_IO_HUP will be set if the connection has been closed locally.
	*
	* %G_IO_ERR will be set if there was an asynchronous error in transmitting data
	* previously enqueued using g_datagram_based_send_messages().
	*
	* Note that on Windows, it is possible for an operation to return
	* %G_IO_ERROR_WOULD_BLOCK even immediately after
	* g_datagram_based_condition_check() has claimed that the #GDatagramBased is
	* ready for writing. Rather than calling g_datagram_based_condition_check() and
	* then writing to the #GDatagramBased if it succeeds, it is generally better to
	* simply try writing right away, and try again later if the initial attempt
	* returns %G_IO_ERROR_WOULD_BLOCK.
	*
	* It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
	* conditions will always be set in the output if they are true. Apart from
	* these flags, the output is guaranteed to be masked by @condition.
	*
	* This call never blocks.
	*
	* Returns: the #GIOCondition mask of the current state
	*
	* Since: 2.48
	*/
	GIOCondition
	g_datagram_based_condition_check (GDatagramBased *datagram_based,
	GIOCondition condition)
	{
	GDatagramBasedInterface *iface;
	GIOCondition out;

	g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), 0);

	iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
	g_assert (iface->condition_check != NULL);

	out = iface->condition_check (datagram_based, condition);

	/* Postconditions. G_IO_OUT and G_IO_HUP are mutually exclusive. G_IO_IN and
	* G_IO_HUP are mutually exclusive. The return value must be a subset of
	* (condition \| G_IO_ERR \| G_IO_HUP). */
	g_return_val_if_fail ((out & (G_IO_OUT \| G_IO_HUP)) != (G_IO_OUT \| G_IO_HUP),
	out & ~G_IO_OUT);
	g_return_val_if_fail ((out & (G_IO_IN \| G_IO_HUP)) != (G_IO_IN \| G_IO_HUP),
	out & ~G_IO_IN);
	g_return_val_if_fail ((out & ~(condition \| G_IO_ERR \| G_IO_HUP)) == 0,
	out & (condition \| G_IO_ERR \| G_IO_HUP));

	return out;
	}

	/**
	* g_datagram_based_condition_wait:
	* @datagram_based: a #GDatagramBased
	* @condition: a #GIOCondition mask to wait for
	* @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
	* to block indefinitely
	* @cancellable: (nullable): a #GCancellable
	* @error: return location for a #GError
	*
	* Waits for up to @timeout microseconds for condition to become true on
	* @datagram_based. If the condition is met, %TRUE is returned.
	*
	* If @cancellable is cancelled before the condition is met, or if @timeout is
	* reached before the condition is met, then %FALSE is returned and @error is
	* set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
	*
	* Returns: %TRUE if the condition was met, %FALSE otherwise
	*
	* Since: 2.48
	*/
	gboolean
	g_datagram_based_condition_wait (GDatagramBased *datagram_based,
	GIOCondition condition,
	gint64 timeout,
	GCancellable *cancellable,
	GError **error)
	{
	GDatagramBasedInterface *iface;
	gboolean out;
	GError *child_error = NULL;

	g_return_val_if_fail (G_IS_DATAGRAM_BASED (datagram_based), FALSE);
	g_return_val_if_fail (cancellable == NULL \|\| G_IS_CANCELLABLE (cancellable),
	FALSE);
	g_return_val_if_fail (error == NULL \|\| *error == NULL, FALSE);

	iface = G_DATAGRAM_BASED_GET_IFACE (datagram_based);
	g_assert (iface->condition_wait != NULL);

	out = iface->condition_wait (datagram_based, condition, timeout,
	cancellable, &child_error);

	/* Postconditions. */
	g_return_val_if_fail (out == (child_error == NULL), FALSE);

	if (child_error != NULL)
	g_propagate_error (error, child_error);

	return out;
	}