Receive data from a socket.
This is the most complicated and fully-featured version of this call. For easier use, see receive and 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 InputVector structs and
vectors.length must be the length of this array. These structs describe the buffers that received data will be scattered into. If
vectors.length is -1, then vectors is assumed to be terminated by a
InputVector with a null buffer pointer.
As a special case, if vectors.length 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
SocketControlMessage instances or
null if no such messages was received. These correspond to the control messages received from
the kernel, one SocketControlMessage per message from the kernel.
This array is null-terminated and must be freed by the caller using
g_free after calling
unref on each element. If messages is
null, any control messages received will be discarded.
messages.length, if non-null, will be set to the number of control messages
received.
If both messages and messages.length are non-null, then
messages.length gives the number of SocketControlMessage
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
SocketMsgFlags 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 receive_message may pass
system-specific flags out).
As with receive, data may be discarded if this 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 throws is set accordingly.
| this |
a Socket |
| address |
a pointer to a SocketAddress pointer, or null |
| vectors |
an array of InputVector structs |
| messages |
a pointer which may be filled with an array of SocketControlMessages, or null |
| flags |
a pointer to an int containing SocketMsgFlags flags |
| cancellable |
a gcancellable or null |
| num_messages |
a pointer which will be filled with the number of elements in |
| num_vectors |
the number of elements in |
|
Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error |