|
Packit |
ae235b |
|
|
Packit |
ae235b |
<html>
|
|
Packit |
ae235b |
<head>
|
|
Packit |
ae235b |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit |
ae235b |
<title>GDatagramBased: GIO Reference Manual</title>
|
|
Packit |
ae235b |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit |
ae235b |
<link rel="home" href="index.html" title="GIO Reference Manual">
|
|
Packit |
ae235b |
<link rel="up" href="networking.html" title="Low-level network support">
|
|
Packit |
ae235b |
<link rel="prev" href="GSocket.html" title="GSocket">
|
|
Packit |
ae235b |
<link rel="next" href="GInetAddress.html" title="GInetAddress">
|
|
Packit |
ae235b |
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
|
Packit |
ae235b |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit |
ae235b |
</head>
|
|
Packit |
ae235b |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Top |
|
|
Packit |
ae235b |
Description |
|
|
Packit |
ae235b |
Object Hierarchy |
|
|
Packit |
ae235b |
Prerequisites |
|
|
Packit |
ae235b |
Known Derived Interfaces |
|
|
Packit |
ae235b |
Known Implementations
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GDatagramBased
|
|
Packit |
ae235b |
GDatagramBased — Low-level datagram communications interface
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Functions
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
gboolean
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
(*GDatagramBasedSourceFunc) ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
gint
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_receive_messages ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
gint
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_send_messages ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GSource *
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_create_source ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GIOCondition
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_condition_check ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
gboolean
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_condition_wait ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Types and Values
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GDatagramBased
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
struct
|
|
Packit |
ae235b |
GDatagramBasedInterface
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Object Hierarchy
|
|
Packit |
ae235b |
GInterface
|
|
Packit |
ae235b |
╰── GDatagramBased
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Prerequisites
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GDatagramBased requires
|
|
Packit |
ae235b |
GObject.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Known Derived Interfaces
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GDatagramBased is required by
|
|
Packit |
ae235b |
GDtlsClientConnection, GDtlsConnection and GDtlsServerConnection.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Known Implementations
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GDatagramBased is implemented by
|
|
Packit |
ae235b |
GSocket.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Includes
|
|
Packit |
ae235b |
#include <gio/gio.h>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Description
|
|
Packit |
ae235b |
A GDatagramBased is a networking interface for representing datagram-based
|
|
Packit |
ae235b |
communications. It is a more or less direct mapping of the core parts of the
|
|
Packit |
ae235b |
BSD socket API in a portable GObject interface. It is implemented by
|
|
Packit |
ae235b |
GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.
|
|
Packit |
ae235b |
GDatagramBased is entirely platform independent, and is intended to be used
|
|
Packit |
ae235b |
alongside higher-level networking APIs such as GIOStream.
|
|
Packit |
ae235b |
It uses vectored scatter/gather I/O by default, allowing for many messages
|
|
Packit |
ae235b |
to be sent or received in a single call. Where possible, implementations of
|
|
Packit |
ae235b |
the interface should take advantage of vectored I/O to minimise processing
|
|
Packit |
ae235b |
or system calls. For example, GSocket uses recvmmsg() and sendmmsg() where
|
|
Packit |
ae235b |
possible. Callers should take advantage of scatter/gather I/O (the use of
|
|
Packit |
ae235b |
multiple buffers per message) to avoid unnecessary copying of data to
|
|
Packit |
ae235b |
assemble or disassemble a message.
|
|
Packit |
ae235b |
Each GDatagramBased operation has a timeout parameter which may be negative
|
|
Packit |
ae235b |
for blocking behaviour, zero for non-blocking behaviour, or positive for
|
|
Packit |
ae235b |
timeout behaviour. A blocking operation blocks until finished or there is an
|
|
Packit |
ae235b |
error. A non-blocking operation will return immediately with a
|
|
Packit |
ae235b |
G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation
|
|
Packit |
ae235b |
will block until the operation is complete or the timeout expires; if the
|
|
Packit |
ae235b |
timeout expires it will return what progress it made, or
|
|
Packit |
ae235b |
G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would
|
|
Packit |
ae235b |
successfully run you can call g_datagram_based_condition_check() or
|
|
Packit |
ae235b |
g_datagram_based_condition_wait() . You can also use
|
|
Packit |
ae235b |
g_datagram_based_create_source() and attach it to a GMainContext to get
|
|
Packit |
ae235b |
callbacks when I/O is possible.
|
|
Packit |
ae235b |
When running a non-blocking operation applications should always be able to
|
|
Packit |
ae235b |
handle getting a G_IO_ERROR_WOULD_BLOCK error even when some other function
|
|
Packit |
ae235b |
said that I/O was possible. This can easily happen in case of a race
|
|
Packit |
ae235b |
condition in the application, but it can also happen for other reasons. For
|
|
Packit |
ae235b |
instance, on Windows a socket is always seen as writable until a write
|
|
Packit |
ae235b |
returns G_IO_ERROR_WOULD_BLOCK .
|
|
Packit |
ae235b |
As with GSocket, GDatagramBaseds can be either connection oriented (for
|
|
Packit |
ae235b |
example, SCTP) or connectionless (for example, UDP). GDatagramBaseds must be
|
|
Packit |
ae235b |
datagram-based, not stream-based. The interface does not cover connection
|
|
Packit |
ae235b |
establishment — use methods on the underlying type to establish a connection
|
|
Packit |
ae235b |
before sending and receiving data through the GDatagramBased API. For
|
|
Packit |
ae235b |
connectionless socket types the target/source address is specified or
|
|
Packit |
ae235b |
received in each I/O operation.
|
|
Packit |
ae235b |
Like most other APIs in GLib, GDatagramBased is not inherently thread safe.
|
|
Packit |
ae235b |
To use a GDatagramBased concurrently from multiple threads, you must
|
|
Packit |
ae235b |
implement your own locking.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Functions
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GDatagramBasedSourceFunc ()
|
|
Packit |
ae235b |
gboolean
|
|
Packit |
ae235b |
(*GDatagramBasedSourceFunc) (GDatagramBased *datagram_based ,
|
|
Packit |
ae235b |
GIOCondition condition ,
|
|
Packit |
ae235b |
gpointer user_data );
|
|
Packit |
ae235b |
This is the function type of the callback used for the GSource
|
|
Packit |
ae235b |
returned by g_datagram_based_create_source() .
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
datagram_based
|
|
Packit |
ae235b |
the GDatagramBased
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
condition
|
|
Packit |
ae235b |
the current condition at the source fired
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
user_data
|
|
Packit |
ae235b |
data passed in by the user
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
G_SOURCE_REMOVE if the source should be removed,
|
|
Packit |
ae235b |
G_SOURCE_CONTINUE otherwise
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.48
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_receive_messages ()
|
|
Packit |
ae235b |
gint
|
|
Packit |
ae235b |
g_datagram_based_receive_messages (GDatagramBased *datagram_based ,
|
|
Packit |
ae235b |
GInputMessage *messages ,
|
|
Packit |
ae235b |
guint num_messages ,
|
|
Packit |
ae235b |
gint flags ,
|
|
Packit |
ae235b |
gint64 timeout ,
|
|
Packit |
ae235b |
GCancellable *cancellable ,
|
|
Packit |
ae235b |
GError **error );
|
|
Packit |
ae235b |
Receive one or more data messages from datagram_based
|
|
Packit |
ae235b |
in one go.
|
|
Packit |
ae235b |
messages
|
|
Packit |
ae235b |
must point to an array of GInputMessage structs and
|
|
Packit |
ae235b |
num_messages
|
|
Packit |
ae235b |
must be the length of this array. Each GInputMessage
|
|
Packit |
ae235b |
contains a pointer to an array of GInputVector structs describing the
|
|
Packit |
ae235b |
buffers that the data received in each message will be written to.
|
|
Packit |
ae235b |
flags
|
|
Packit |
ae235b |
modify how all messages are received. The commonly available
|
|
Packit |
ae235b |
arguments for this are available in the GSocketMsgFlags enum, but the
|
|
Packit |
ae235b |
values there are the same as the system values, and the flags
|
|
Packit |
ae235b |
are passed in as-is, so you can pass in system-specific flags too. These
|
|
Packit |
ae235b |
flags affect the overall receive operation. Flags affecting individual
|
|
Packit |
ae235b |
messages are returned in GInputMessage.flags.
|
|
Packit |
ae235b |
The other members of GInputMessage are treated as described in its
|
|
Packit |
ae235b |
documentation.
|
|
Packit |
ae235b |
If timeout
|
|
Packit |
ae235b |
is negative the call will block until num_messages
|
|
Packit |
ae235b |
have been
|
|
Packit |
ae235b |
received, the connection is closed remotely (EOS), cancellable
|
|
Packit |
ae235b |
is cancelled,
|
|
Packit |
ae235b |
or an error occurs.
|
|
Packit |
ae235b |
If timeout
|
|
Packit |
ae235b |
is 0 the call will return up to num_messages
|
|
Packit |
ae235b |
without blocking,
|
|
Packit |
ae235b |
or G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
|
|
Packit |
ae235b |
to be received.
|
|
Packit |
ae235b |
If timeout
|
|
Packit |
ae235b |
is positive the call will block on the same conditions as if
|
|
Packit |
ae235b |
timeout
|
|
Packit |
ae235b |
were negative. If the timeout is reached
|
|
Packit |
ae235b |
before any messages are received, G_IO_ERROR_TIMED_OUT is returned,
|
|
Packit |
ae235b |
otherwise it will return the number of messages received before timing out.
|
|
Packit |
ae235b |
(Note: This is effectively the behaviour of MSG_WAITFORONE with
|
|
Packit |
ae235b |
recvmmsg() .)
|
|
Packit |
ae235b |
To be notified when messages are available, wait for the G_IO_IN condition.
|
|
Packit |
ae235b |
Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from
|
|
Packit |
ae235b |
g_datagram_based_receive_messages() even if you were previously notified of a
|
|
Packit |
ae235b |
G_IO_IN condition.
|
|
Packit |
ae235b |
If the remote peer closes the connection, any messages queued in the
|
|
Packit |
ae235b |
underlying receive buffer will be returned, and subsequent calls to
|
|
Packit |
ae235b |
g_datagram_based_receive_messages() will return 0 (with no error set).
|
|
Packit |
ae235b |
If the connection is shut down or closed (by calling g_socket_close() or
|
|
Packit |
ae235b |
g_socket_shutdown() with shutdown_read
|
|
Packit |
ae235b |
set, if it’s a GSocket, for
|
|
Packit |
ae235b |
example), all calls to this function will return G_IO_ERROR_CLOSED .
|
|
Packit |
ae235b |
On error -1 is returned and error
|
|
Packit |
ae235b |
is set accordingly. An error will only
|
|
Packit |
ae235b |
be returned if zero messages could be received; otherwise the number of
|
|
Packit |
ae235b |
messages successfully received before the error will be returned. If
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
is cancelled, G_IO_ERROR_CANCELLED is returned as with any
|
|
Packit |
ae235b |
other error.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
datagram_based
|
|
Packit |
ae235b |
a GDatagramBased
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
messages
|
|
Packit |
ae235b |
an array of GInputMessage structs.
|
|
Packit |
ae235b |
[array length=num_messages]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
num_messages
|
|
Packit |
ae235b |
the number of elements in messages
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
flags
|
|
Packit |
ae235b |
an int containing GSocketMsgFlags flags for the overall operation
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
timeout
|
|
Packit |
ae235b |
the maximum time (in microseconds) to wait, 0 to not block, or -1
|
|
Packit |
ae235b |
to block indefinitely
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
a GCancellable .
|
|
Packit |
ae235b |
[nullable]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
error
|
|
Packit |
ae235b |
return location for a GError
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
number of messages received, or -1 on error. Note that the number
|
|
Packit |
ae235b |
of messages received may be smaller than num_messages
|
|
Packit |
ae235b |
if timeout
|
|
Packit |
ae235b |
is
|
|
Packit |
ae235b |
zero or positive, if the peer closed the connection, or if num_messages
|
|
Packit |
ae235b |
was larger than UIO_MAXIOV (1024), in which case the caller may re-try
|
|
Packit |
ae235b |
to receive the remaining messages.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.48
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_send_messages ()
|
|
Packit |
ae235b |
gint
|
|
Packit |
ae235b |
g_datagram_based_send_messages (GDatagramBased *datagram_based ,
|
|
Packit |
ae235b |
GOutputMessage *messages ,
|
|
Packit |
ae235b |
guint num_messages ,
|
|
Packit |
ae235b |
gint flags ,
|
|
Packit |
ae235b |
gint64 timeout ,
|
|
Packit |
ae235b |
GCancellable *cancellable ,
|
|
Packit |
ae235b |
GError **error );
|
|
Packit |
ae235b |
Send one or more data messages from datagram_based
|
|
Packit |
ae235b |
in one go.
|
|
Packit |
ae235b |
messages
|
|
Packit |
ae235b |
must point to an array of GOutputMessage structs and
|
|
Packit |
ae235b |
num_messages
|
|
Packit |
ae235b |
must be the length of this array. Each GOutputMessage
|
|
Packit |
ae235b |
contains an address to send the data to, and a pointer to an array of
|
|
Packit |
ae235b |
GOutputVector structs to describe the buffers that the data to be sent
|
|
Packit |
ae235b |
for each message will be gathered from.
|
|
Packit |
ae235b |
flags
|
|
Packit |
ae235b |
modify how the message is sent. The commonly available arguments
|
|
Packit |
ae235b |
for this are available in the GSocketMsgFlags enum, but the
|
|
Packit |
ae235b |
values there are the same as the system values, and the flags
|
|
Packit |
ae235b |
are passed in as-is, so you can pass in system-specific flags too.
|
|
Packit |
ae235b |
The other members of GOutputMessage are treated as described in its
|
|
Packit |
ae235b |
documentation.
|
|
Packit |
ae235b |
If timeout
|
|
Packit |
ae235b |
is negative the call will block until num_messages
|
|
Packit |
ae235b |
have been
|
|
Packit |
ae235b |
sent, cancellable
|
|
Packit |
ae235b |
is cancelled, or an error occurs.
|
|
Packit |
ae235b |
If timeout
|
|
Packit |
ae235b |
is 0 the call will send up to num_messages
|
|
Packit |
ae235b |
without blocking,
|
|
Packit |
ae235b |
or will return G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
|
|
Packit |
ae235b |
If timeout
|
|
Packit |
ae235b |
is positive the call will block on the same conditions as if
|
|
Packit |
ae235b |
timeout
|
|
Packit |
ae235b |
were negative. If the timeout is reached before any messages are
|
|
Packit |
ae235b |
sent, G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
|
|
Packit |
ae235b |
of messages sent before timing out.
|
|
Packit |
ae235b |
To be notified when messages can be sent, wait for the G_IO_OUT condition.
|
|
Packit |
ae235b |
Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from
|
|
Packit |
ae235b |
g_datagram_based_send_messages() even if you were previously notified of a
|
|
Packit |
ae235b |
G_IO_OUT condition. (On Windows in particular, this is very common due to
|
|
Packit |
ae235b |
the way the underlying APIs work.)
|
|
Packit |
ae235b |
If the connection is shut down or closed (by calling g_socket_close() or
|
|
Packit |
ae235b |
g_socket_shutdown() with shutdown_write
|
|
Packit |
ae235b |
set, if it’s a GSocket, for
|
|
Packit |
ae235b |
example), all calls to this function will return G_IO_ERROR_CLOSED .
|
|
Packit |
ae235b |
On error -1 is returned and error
|
|
Packit |
ae235b |
is set accordingly. An error will only
|
|
Packit |
ae235b |
be returned if zero messages could be sent; otherwise the number of messages
|
|
Packit |
ae235b |
successfully sent before the error will be returned. If cancellable
|
|
Packit |
ae235b |
is
|
|
Packit |
ae235b |
cancelled, G_IO_ERROR_CANCELLED is returned as with any other error.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
datagram_based
|
|
Packit |
ae235b |
a GDatagramBased
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
messages
|
|
Packit |
ae235b |
an array of GOutputMessage structs.
|
|
Packit |
ae235b |
[array length=num_messages]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
num_messages
|
|
Packit |
ae235b |
the number of elements in messages
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
flags
|
|
Packit |
ae235b |
an int containing GSocketMsgFlags flags
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
timeout
|
|
Packit |
ae235b |
the maximum time (in microseconds) to wait, 0 to not block, or -1
|
|
Packit |
ae235b |
to block indefinitely
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
a GCancellable .
|
|
Packit |
ae235b |
[nullable]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
error
|
|
Packit |
ae235b |
return location for a GError
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
number of messages sent, or -1 on error. Note that the number of
|
|
Packit |
ae235b |
messages sent may be smaller than num_messages
|
|
Packit |
ae235b |
if timeout
|
|
Packit |
ae235b |
is zero
|
|
Packit |
ae235b |
or positive, or if num_messages
|
|
Packit |
ae235b |
was larger than UIO_MAXIOV (1024), in
|
|
Packit |
ae235b |
which case the caller may re-try to send the remaining messages.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.48
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_create_source ()
|
|
Packit |
ae235b |
GSource *
|
|
Packit |
ae235b |
g_datagram_based_create_source (GDatagramBased *datagram_based ,
|
|
Packit |
ae235b |
GIOCondition condition ,
|
|
Packit |
ae235b |
GCancellable *cancellable );
|
|
Packit |
ae235b |
Creates a GSource that can be attached to a GMainContext to monitor for
|
|
Packit |
ae235b |
the availability of the specified condition
|
|
Packit |
ae235b |
on the GDatagramBased. The
|
|
Packit |
ae235b |
GSource keeps a reference to the datagram_based
|
|
Packit |
ae235b |
.
|
|
Packit |
ae235b |
The callback on the source is of the GDatagramBasedSourceFunc type.
|
|
Packit |
ae235b |
It is meaningless to specify G_IO_ERR or G_IO_HUP in condition
|
|
Packit |
ae235b |
; these
|
|
Packit |
ae235b |
conditions will always be reported in the callback if they are true.
|
|
Packit |
ae235b |
If non-NULL , cancellable
|
|
Packit |
ae235b |
can be used to cancel the source, which will
|
|
Packit |
ae235b |
cause the source to trigger, reporting the current condition (which is
|
|
Packit |
ae235b |
likely 0 unless cancellation happened at the same time as a condition
|
|
Packit |
ae235b |
change). You can check for this in the callback using
|
|
Packit |
ae235b |
g_cancellable_is_cancelled() .
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
datagram_based
|
|
Packit |
ae235b |
a GDatagramBased
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
condition
|
|
Packit |
ae235b |
a GIOCondition mask to monitor
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
a GCancellable.
|
|
Packit |
ae235b |
[nullable]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
a newly allocated GSource.
|
|
Packit |
ae235b |
[transfer full]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.48
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_condition_check ()
|
|
Packit |
ae235b |
GIOCondition
|
|
Packit |
ae235b |
g_datagram_based_condition_check (GDatagramBased *datagram_based ,
|
|
Packit |
ae235b |
GIOCondition condition );
|
|
Packit |
ae235b |
Checks on the readiness of datagram_based
|
|
Packit |
ae235b |
to perform operations. The
|
|
Packit |
ae235b |
operations specified in condition
|
|
Packit |
ae235b |
are checked for and masked against the
|
|
Packit |
ae235b |
currently-satisfied conditions on datagram_based
|
|
Packit |
ae235b |
. The result is returned.
|
|
Packit |
ae235b |
G_IO_IN will be set in the return value if data is available to read with
|
|
Packit |
ae235b |
g_datagram_based_receive_messages() , or if the connection is closed remotely
|
|
Packit |
ae235b |
(EOS); and if the datagram_based has not been closed locally using some
|
|
Packit |
ae235b |
implementation-specific method (such as g_socket_close() or
|
|
Packit |
ae235b |
g_socket_shutdown() with shutdown_read
|
|
Packit |
ae235b |
set, if it’s a GSocket).
|
|
Packit |
ae235b |
If the connection is shut down or closed (by calling g_socket_close() or
|
|
Packit |
ae235b |
g_socket_shutdown() with shutdown_read
|
|
Packit |
ae235b |
set, if it’s a GSocket, for
|
|
Packit |
ae235b |
example), all calls to this function will return G_IO_ERROR_CLOSED .
|
|
Packit |
ae235b |
G_IO_OUT will be set if it is expected that at least one byte can be sent
|
|
Packit |
ae235b |
using g_datagram_based_send_messages() without blocking. It will not be set
|
|
Packit |
ae235b |
if the datagram_based has been closed locally.
|
|
Packit |
ae235b |
G_IO_HUP will be set if the connection has been closed locally.
|
|
Packit |
ae235b |
G_IO_ERR will be set if there was an asynchronous error in transmitting data
|
|
Packit |
ae235b |
previously enqueued using g_datagram_based_send_messages() .
|
|
Packit |
ae235b |
Note that on Windows, it is possible for an operation to return
|
|
Packit |
ae235b |
G_IO_ERROR_WOULD_BLOCK even immediately after
|
|
Packit |
ae235b |
g_datagram_based_condition_check() has claimed that the GDatagramBased is
|
|
Packit |
ae235b |
ready for writing. Rather than calling g_datagram_based_condition_check() and
|
|
Packit |
ae235b |
then writing to the GDatagramBased if it succeeds, it is generally better to
|
|
Packit |
ae235b |
simply try writing right away, and try again later if the initial attempt
|
|
Packit |
ae235b |
returns G_IO_ERROR_WOULD_BLOCK .
|
|
Packit |
ae235b |
It is meaningless to specify G_IO_ERR or G_IO_HUP in condition
|
|
Packit |
ae235b |
; these
|
|
Packit |
ae235b |
conditions will always be set in the output if they are true. Apart from
|
|
Packit |
ae235b |
these flags, the output is guaranteed to be masked by condition
|
|
Packit |
ae235b |
.
|
|
Packit |
ae235b |
This call never blocks.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
datagram_based
|
|
Packit |
ae235b |
a GDatagramBased
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
condition
|
|
Packit |
ae235b |
a GIOCondition mask to check
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
the GIOCondition mask of the current state
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.48
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_datagram_based_condition_wait ()
|
|
Packit |
ae235b |
gboolean
|
|
Packit |
ae235b |
g_datagram_based_condition_wait (GDatagramBased *datagram_based ,
|
|
Packit |
ae235b |
GIOCondition condition ,
|
|
Packit |
ae235b |
gint64 timeout ,
|
|
Packit |
ae235b |
GCancellable *cancellable ,
|
|
Packit |
ae235b |
GError **error );
|
|
Packit |
ae235b |
Waits for up to timeout
|
|
Packit |
ae235b |
microseconds for condition to become true on
|
|
Packit |
ae235b |
datagram_based
|
|
Packit |
ae235b |
. If the condition is met, TRUE is returned.
|
|
Packit |
ae235b |
If cancellable
|
|
Packit |
ae235b |
is cancelled before the condition is met, or if timeout
|
|
Packit |
ae235b |
is
|
|
Packit |
ae235b |
reached before the condition is met, then FALSE is returned and error
|
|
Packit |
ae235b |
is
|
|
Packit |
ae235b |
set appropriately (G_IO_ERROR_CANCELLED or G_IO_ERROR_TIMED_OUT ).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
datagram_based
|
|
Packit |
ae235b |
a GDatagramBased
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
condition
|
|
Packit |
ae235b |
a GIOCondition mask to wait for
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
timeout
|
|
Packit |
ae235b |
the maximum time (in microseconds) to wait, 0 to not block, or -1
|
|
Packit |
ae235b |
to block indefinitely
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
a GCancellable.
|
|
Packit |
ae235b |
[nullable]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
error
|
|
Packit |
ae235b |
return location for a GError
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
TRUE if the condition was met, FALSE otherwise
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.48
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Types and Values
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GDatagramBased
|
|
Packit |
ae235b |
typedef struct _GDatagramBased GDatagramBased;
|
|
Packit |
ae235b |
Interface for socket-like objects with datagram semantics.
|
|
Packit |
ae235b |
Since: 2.48
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
struct GDatagramBasedInterface
|
|
Packit |
ae235b |
struct GDatagramBasedInterface {
|
|
Packit |
ae235b |
GTypeInterface g_iface;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
/* Virtual table */
|
|
Packit |
ae235b |
gint (*receive_messages) (GDatagramBased *datagram_based,
|
|
Packit |
ae235b |
GInputMessage *messages,
|
|
Packit |
ae235b |
guint num_messages,
|
|
Packit |
ae235b |
gint flags,
|
|
Packit |
ae235b |
gint64 timeout,
|
|
Packit |
ae235b |
GCancellable *cancellable,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
gint (*send_messages) (GDatagramBased *datagram_based,
|
|
Packit |
ae235b |
GOutputMessage *messages,
|
|
Packit |
ae235b |
guint num_messages,
|
|
Packit |
ae235b |
gint flags,
|
|
Packit |
ae235b |
gint64 timeout,
|
|
Packit |
ae235b |
GCancellable *cancellable,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GSource *(*create_source) (GDatagramBased *datagram_based,
|
|
Packit |
ae235b |
GIOCondition condition,
|
|
Packit |
ae235b |
GCancellable *cancellable);
|
|
Packit |
ae235b |
GIOCondition (*condition_check) (GDatagramBased *datagram_based,
|
|
Packit |
ae235b |
GIOCondition condition);
|
|
Packit |
ae235b |
gboolean (*condition_wait) (GDatagramBased *datagram_based,
|
|
Packit |
ae235b |
GIOCondition condition,
|
|
Packit |
ae235b |
gint64 timeout,
|
|
Packit |
ae235b |
GCancellable *cancellable,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
};
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Provides an interface for socket-like objects which have datagram semantics,
|
|
Packit |
ae235b |
following the Berkeley sockets API. The interface methods are thin wrappers
|
|
Packit |
ae235b |
around the corresponding virtual methods, and no pre-processing of inputs is
|
|
Packit |
ae235b |
implemented — so implementations of this API must handle all functionality
|
|
Packit |
ae235b |
documented in the interface methods.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Members
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
receive_messages ()
|
|
Packit |
ae235b |
Virtual method for g_datagram_based_receive_messages() .
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
send_messages ()
|
|
Packit |
ae235b |
Virtual method for g_datagram_based_send_messages() .
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
create_source ()
|
|
Packit |
ae235b |
Virtual method for g_datagram_based_create_source() .
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
condition_check ()
|
|
Packit |
ae235b |
Virtual method for g_datagram_based_condition_check() .
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
condition_wait ()
|
|
Packit |
ae235b |
Virtual method for
|
|
Packit |
ae235b |
g_datagram_based_condition_wait() .
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.48
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
See Also
|
|
Packit |
ae235b |
GSocket, <gnetworking.h>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Generated by GTK-Doc V1.27
|
|
Packit |
ae235b |
</body>
|
|
Packit |
ae235b |
</html>
|