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

@@ -2004,6 +2004,7 @@ GSocketType
 GSocketProtocol
 GSocketMsgFlags
 GInputVector
+GInputMessage
 GOutputVector
 GOutputMessage
 g_socket_new

gio/giotypes.h

@@ -408,6 +408,60 @@ struct _GInputVector {
   gsize size;
 };
 
+/**
+ * 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.