Gio.Socket.receive_messages

### Method

# Gio Socketreceive_messages

since: 2.48

#### Declaration

    gint
    g_socket_receive_messages (
      GSocket* socket,
      GInputMessage* messages,
      guint num_messages,
      gint flags,
      GCancellable* cancellable,
      GError** error
    )

#### Description

Receive multiple data messages from `socket` in one go. This is the most complicated and fully-featured version of this call. For easier use, see g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message().

`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. Using multiple `GInputVectors` is more memory-efficient than manually copying data out of a single buffer to multiple sources, and more system-call-efficient than making multiple calls to g_socket_receive(), such as in scenarios where a lot of data packets need to be received (e.g. high-bandwidth video streaming over RTP/UDP).

`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 `GSocket:blocking` is `TRUE` the call will block until `num_messages` have been received, or the end of the stream is reached.

If `GSocket:blocking` is `FALSE` 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.

In blocking mode, if `GSocket:timeout` is positive and is reached before any messages are received, `G_IO_ERROR_TIMED_OUT` is returned, otherwise up to `num_messages` are returned. (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_socket_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 operating system will be returned, and subsequent calls to `g_socket_receive_messages()` will return 0 (with no error set).

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.

Available since: 2.48

#### Parameters

`messages`

  Type: An array of `GInputMessage`

  An array of `GInputMessage` structs.

  The length of the array is specified in the `num_messages` argument.
  The data is owned by the caller of the method.

`num_messages`

  Type: `guint`

  The number of elements in `messages`.

`flags`

  Type: `gint`

  An int containing `GSocketMsgFlags` flags for the overall operation, which may additionally contain other platform specific flags

`cancellable`

  Type: `GCancellable`

  A %GCancellable or `NULL`.

  The argument can be `NULL`.
  The data is owned by the caller of the method.

`error`

  Type: `GError **`

  The return location for a recoverable error.

  The argument can be `NULL`.
  If the return location is not `NULL`, then you must initialize it to a `NULL` `GError*`.
  The argument will be left initialized to `NULL` by the method if there are no errors.
  In case of error, the argument will be set to a newly allocated `GError`; the caller will take ownership of the data, and be responsible for freeing it.

#### Return value

Type: `gint`

Number of messages received, or -1 on error. Note that the number of messages received may be smaller than `num_messages` if in non-blocking mode, 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.