Gio.Socket.receive_message

### Method

# Gio Socketreceive_message

since: 2.22

#### Declaration [src]

    gssize
    g_socket_receive_message (
      GSocket* socket,
      GSocketAddress** address,
      GInputVector* vectors,
      gint num_vectors,
      GSocketControlMessage*** messages,
      gint* num_messages,
      gint* flags,
      GCancellable* cancellable,
      GError** error
    )

#### Description [src]

Receive data from a socket. For receiving multiple messages, see g_socket_receive_messages(); for easier use, see `g_socket_receive()` and g_socket_receive_from().

If `address` is non-`NULL` then `address` will be set equal to the source address of the received packet. `address` is owned by the caller.

`vector` must point to an array of `GInputVector` structs and `num_vectors` must be the length of this array. These structs describe the buffers that received data will be scattered into. If `num_vectors` is -1, then `vectors` is assumed to be terminated by a `GInputVector` with a `NULL` buffer pointer.

As a special case, if `num_vectors` is 0 (in which case, `vectors` may of course be `NULL`), then a single byte is received and discarded. This is to facilitate the common practice of sending a single ‘\0’ byte for the purposes of transferring ancillary data.

`messages`, if non-`NULL`, will be set to point to a newly-allocated array of `GSocketControlMessage` instances or `NULL` if no such messages was received. These correspond to the control messages received from the kernel, one `GSocketControlMessage` per message from the kernel. This array is `NULL`-terminated and must be freed by the caller using `g_free()` after calling `g_object_unref()` on each element. If `messages` is `NULL`, any control messages received will be discarded.

`num_messages`, if non-`NULL`, will be set to the number of control messages received.

If both `messages` and `num_messages` are non-`NULL`, then `num_messages` gives the number of `GSocketControlMessage` instances in `messages` (ie: not including the `NULL` terminator).

`flags` is an in/out parameter. 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 (and `g_socket_receive_message()` may pass system-specific flags out). Flags passed in to the parameter affect the receive operation; flags returned out of it are relevant to the specific returned message.

As with g_socket_receive(), data may be discarded if `socket` is `G_SOCKET_TYPE_DATAGRAM` or `G_SOCKET_TYPE_SEQPACKET` and you do not provide enough buffer space to read a complete message. You can pass `G_SOCKET_MSG_PEEK` in `flags` to peek at the current message without removing it from the receive queue, but there is no portable way to find out the length of the message other than by reading it into a sufficiently-large buffer.

If the socket is in blocking mode the call will block until there is some data to receive, the connection is closed, or there is an error. If there is no data available and the socket is in non-blocking mode, a `G_IO_ERROR_WOULD_BLOCK` error will be returned. To be notified when data is available, wait for the `G_IO_IN` condition.

On error -1 is returned and `error` is set accordingly.

Available since: 2.22

#### Parameters

`address`

  Type: `GSocketAddress`

  A pointer to a `GSocketAddress` pointer, or `NULL`.

  The argument will be set by the function.
  The argument can be `NULL`.
  The caller of the method takes ownership of the returned data, and is responsible for freeing it.

`vectors`

  Type: An array of `GInputVector`

  An array of `GInputVector` structs.

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

`num_vectors`

  Type: `gint`

  The number of elements in `vectors`, or -1.

`messages`

  Type: An array of `GSocketControlMessage**`

  A pointer which may be filled with an array of `GSocketControlMessages`, or `NULL`.

  The argument will be set by the function.
  The argument can be set to `NULL` by the method.
  The argument can be `NULL`.
  The length of the array is specified in the `num_messages` argument.
  The caller of the method takes ownership of the returned data, and is responsible for freeing it.

`num_messages`

  Type: `gint*`

  A pointer which will be filled with the number of elements in `messages`, or `NULL`.

  The argument will be set by the function.

`flags`

  Type: `gint*`

  A pointer to an int containing `GSocketMsgFlags` flags, which may additionally contain other platform specific flags.

  The argument will be modified by the function.

`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: `gssize`

Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error.