Learn R Programming

RGtk2 (version 2.20.31)

gSocketReceiveMessage: gSocketReceiveMessage

Description

Receive data from a socket. This is the most complicated and fully-featured version of this call. For easier use, see gSocketReceive and gSocketReceiveFrom.

Usage

gSocketReceiveMessage(object, flags = 0, cancellable = NULL, .errwarn = TRUE)

Arguments

object
flags
a pointer to an int containing GSocketMsgFlags flags
cancellable
a GCancellable or NULL
.errwarn
Whether to issue a warning on error or fail silently

Value

A list containing the following elements:
retval
[integer] Number of bytes read, or -1 on error
address
a pointer to a GSocketAddress pointer, or NULL
vectors
a list of GInputVector structs
messages
a pointer which will be filled with a list of GSocketControlMessages, or NULL
num.messages
a pointer which will be filled with the number of elements in messages, or NULL
error
a GError pointer, or NULL

Details

If address is non-NULL then address will be set equal to the source the received packet. vector must point to a list of GInputVector structs and num.vectors must be the length of this list. 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. These correspond to the control messages received from the kernel, one GSocketControlMessage per message from the kernel. 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 gSocketReceiveMessage may pass system-specific flags out). As with gSocketReceive, 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 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. Since 2.22