1
\alias{gSocketReceiveMessage}
2
\name{gSocketReceiveMessage}
3
\title{gSocketReceiveMessage}
4
\description{Receive data from a socket. This is the most complicated and
5
fully-featured version of this call. For easier use, see
6
\code{\link{gSocketReceive}} and \code{\link{gSocketReceiveFrom}}.}
7
\usage{gSocketReceiveMessage(object, flags = 0, cancellable = NULL, .errwarn = TRUE)}
9
\item{\verb{object}}{a \code{\link{GSocket}}}
10
\item{\verb{flags}}{a pointer to an int containing \verb{GSocketMsgFlags} flags}
11
\item{\verb{cancellable}}{a \code{\link{GCancellable}} or \code{NULL}}
12
\item{.errwarn}{Whether to issue a warning on error or fail silently}
14
\details{If \code{address} is non-\code{NULL} then \code{address} will be set equal to the
15
source the received packet.
16
\code{vector} must point to a list of \verb{GInputVector} structs and
17
\code{num.vectors} must be the length of this list. These structs
18
describe the buffers that received data will be scattered into.
19
If \code{num.vectors} is -1, then \code{vectors} is assumed to be terminated
20
by a \verb{GInputVector} with a \code{NULL} buffer pointer.
22
As a special case, if \code{num.vectors} is 0 (in which case, \code{vectors}
23
may of course be \code{NULL}), then a single byte is received and
24
discarded. This is to facilitate the common practice of sending a
25
single '\\0' byte for the purposes of transferring ancillary data.
26
\code{messages}, if non-\code{NULL}, will be set to point to a newly-allocated
27
array of \code{\link{GSocketControlMessage}} instances. These correspond to the
28
control messages received from the kernel, one
29
\code{\link{GSocketControlMessage}} per message from the kernel. If
30
\code{messages} is \code{NULL}, any control messages received will be
32
\code{num.messages}, if non-\code{NULL}, will be set to the number of control
35
If both \code{messages} and \code{num.messages} are non-\code{NULL}, then
36
\code{num.messages} gives the number of \code{\link{GSocketControlMessage}} instances
37
in \code{messages} (ie: not including the \code{NULL} terminator).
38
\code{flags} is an in/out parameter. The commonly available arguments
39
for this are available in the \verb{GSocketMsgFlags} enum, but the
40
values there are the same as the system values, and the flags
41
are passed in as-is, so you can pass in system-specific flags too
42
(and \code{\link{gSocketReceiveMessage}} may pass system-specific flags out).
44
As with \code{\link{gSocketReceive}}, data may be discarded if \code{socket} is
45
\code{G_SOCKET_TYPE_DATAGRAM} or \code{G_SOCKET_TYPE_SEQPACKET} and you do not
46
provide enough buffer space to read a complete message. You can pass
47
\code{G_SOCKET_MSG_PEEK} in \code{flags} to peek at the current message without
48
removing it from the receive queue, but there is no portable way to find
49
out the length of the message other than by reading it into a
50
sufficiently-large buffer.
52
If the socket is in blocking mode the call will block until there
53
is some data to receive or there is an error. If there is no data
54
available and the socket is in non-blocking mode, a
55
\code{G_IO_ERROR_WOULD_BLOCK} error will be returned. To be notified when
56
data is available, wait for the \code{G_IO_IN} condition.
58
On error -1 is returned and \code{error} is set accordingly.
61
A list containing the following elements:
62
\item{retval}{[integer] Number of bytes read, or -1 on error}
63
\item{\verb{address}}{a pointer to a \code{\link{GSocketAddress}} pointer, or \code{NULL}}
64
\item{\verb{vectors}}{a list of \verb{GInputVector} structs}
65
\item{\verb{messages}}{a pointer which will be filled with a list of
66
\verb{GSocketControlMessages}, or \code{NULL}}
67
\item{\verb{num.messages}}{a pointer which will be filled with the number of
68
elements in \code{messages}, or \code{NULL}}
69
\item{\verb{error}}{a \code{\link{GError}} pointer, or \code{NULL}}
71
\author{Derived by RGtkGen from GTK+ documentation}
added
removed
man/gSocketReceiveMessage.Rd
