[glib] giotypes: Add GInputMessage struct

[Philip Withnall <pwithnall src gnome org>]

commit 8c4c16ddf405ecd93b1df682cbbbca1d7cfad9ba
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Wed Jul 29 11:36:50 2015 +0100

    giotypes: Add GInputMessage struct
    
    This complements the GOutputMessage struct. It will shortly be used for
    adding a g_socket_receive_messages() function, but needs to be committed
    first to allow some internal refactoring of GSocket.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=751924

 docs/reference/gio/gio-sections.txt |    1 +
 gio/giotypes.h                      |   54 +++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index b136cdc..54bb966 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -2004,6 +2004,7 @@ GSocketType
 GSocketProtocol
 GSocketMsgFlags
 GInputVector
+GInputMessage
 GOutputVector
 GOutputMessage
 g_socket_new
diff --git a/gio/giotypes.h b/gio/giotypes.h
index 372e67c..65aa550 100644
--- a/gio/giotypes.h
+++ b/gio/giotypes.h
@@ -409,6 +409,60 @@ struct _GInputVector {
 };
 
 /**
+ * GInputMessage:
+ * @address: (optional) (out) (transfer full): return location
+ *   for a #GSocketAddress, or %NULL
+ * @vectors: (array length=num_vectors) (out): pointer to an
+ *   array of input vectors
+ * @num_vectors: the number of input vectors pointed to by @vectors
+ * @bytes_received: (out): will be set to the number of bytes that have been
+ *   received
+ * @flags: (out): collection of #GSocketMsgFlags for the received message,
+ *   outputted by the call
+ * @control_messages: (array length=num_control_messages) (optional)
+ *   (out) (transfer full): return location for a
+ *   caller-allocated array of #GSocketControlMessages, or %NULL
+ * @num_control_messages: (out) (optional): return location for the number of
+ *   elements in @control_messages
+ *
+ * Structure used for scatter/gather data input when receiving multiple
+ * messages or packets in one go. You generally pass in an array of empty
+ * #GInputVectors and the operation will use all the buffers as if they
+ * were one buffer, and will set @bytes_received to the total number of bytes
+ * received across all #GInputVectors.
+ *
+ * This structure closely mirrors `struct mmsghdr` and `struct msghdr` from
+ * the POSIX sockets API (see `man 2 recvmmsg`).
+ *
+ * If @address is non-%NULL then it is set to the source address the message
+ * was received from, and the caller must free it afterwards.
+ *
+ * If @control_messages is non-%NULL then it is set to an array of control
+ * messages received with the message (if any), and the caller must free it
+ * afterwards. @num_control_messages is set to the number of elements in
+ * this array, which may be zero.
+ *
+ * Flags relevant to this message will be returned in @flags. For example,
+ * `MSG_EOR` or `MSG_TRUNC`.
+ *
+ * Since: 2.48
+ */
+typedef struct _GInputMessage GInputMessage;
+
+struct _GInputMessage {
+  GSocketAddress         **address;
+
+  GInputVector            *vectors;
+  guint                    num_vectors;
+
+  gsize                    bytes_received;
+  gint                     flags;
+
+  GSocketControlMessage ***control_messages;
+  guint                   *num_control_messages;
+};
+
+/**
  * GOutputVector:
  * @buffer: Pointer to a buffer of data to read.
  * @size: the size of @buffer.