Socket.receiveMessages

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.

class Socket
int
receiveMessages

Parameters

messages GInputMessage[]

an array of #GInputMessage structs

flags int

an int containing #GSocketMsgFlags flags for the overall operation

cancellable Cancellable

a %GCancellable or %NULL

Return: 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.

Throws

GException on failure.

Meta

Since

2.48