Method
GioSocketreceive_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:
GSocketAddressA pointer to a
GSocketAddresspointer, orNULL.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
GInputVectorAn array of
GInputVectorstructs.The length of the array is specified in the num_vectorsargument.The data is owned by the caller of the method. num_vectors-
Type:
gintThe number of elements in
vectors, or -1. messages-
Type: An array of
GSocketControlMessage**A pointer which may be filled with an array of
GSocketControlMessages, orNULL.The argument will be set by the function. The argument can be set to NULLby the method.The argument can be NULL.The length of the array is specified in the num_messagesargument.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, orNULL.The argument will be set by the function. flags-
Type:
gint*A pointer to an int containing
GSocketMsgFlagsflags, which may additionally contain other platform specific flags.The argument will be modified by the function. cancellable-
Type:
GCancellableA %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 aNULLGError*.The argument will be left initialized to NULLby 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.