diff options
Diffstat (limited to 'gir/gio-2.0.c')
| -rw-r--r-- | gir/gio-2.0.c | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 7dcb1739..ffb0161e 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -4961,6 +4961,63 @@ /** + * SECTION:gdatagrambased + * @short_description: Low-level datagram communications interface + * @include: gio/gio.h + * @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h] + * + * A #GDatagramBased is a networking interface for representing datagram-based + * communications. It is a more or less direct mapping of the core parts of the + * BSD socket API in a portable GObject interface. It is implemented by + * #GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows. + * + * #GDatagramBased is entirely platform independent, and is intended to be used + * alongside higher-level networking APIs such as #GIOStream. + * + * It uses vectored scatter/gather I/O by default, allowing for many messages + * to be sent or received in a single call. Where possible, implementations of + * the interface should take advantage of vectored I/O to minimise processing + * or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where + * possible. Callers should take advantage of scatter/gather I/O (the use of + * multiple buffers per message) to avoid unnecessary copying of data to + * assemble or disassemble a message. + * + * Each #GDatagramBased operation has a timeout parameter which may be negative + * for blocking behaviour, zero for non-blocking behaviour, or positive for + * timeout behaviour. A blocking operation blocks until finished or there is an + * error. A non-blocking operation will return immediately with a + * %G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation + * will block until the operation is complete or the timeout expires; if the + * timeout expires it will return what progress it made, or + * %G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would + * successfully run you can call g_datagram_based_condition_check() or + * g_datagram_based_condition_wait(). You can also use + * g_datagram_based_create_source() and attach it to a #GMainContext to get + * callbacks when I/O is possible. + * + * When running a non-blocking operation applications should always be able to + * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function + * said that I/O was possible. This can easily happen in case of a race + * condition in the application, but it can also happen for other reasons. For + * instance, on Windows a socket is always seen as writable until a write + * returns %G_IO_ERROR_WOULD_BLOCK. + * + * As with #GSocket, #GDatagramBaseds can be either connection oriented or + * connectionless. The interface does not cover connection establishment — use + * methods on the underlying type to establish a connection before sending and + * receiving data through the #GDatagramBased API. For connectionless socket + * types the target/source address is specified or received in each I/O + * operation. + * + * Like most other APIs in GLib, #GDatagramBased is not inherently thread safe. + * To use a #GDatagramBased concurrently from multiple threads, you must + * implement your own locking. + * + * Since: 2.48 + */ + + +/** * SECTION:gdatainputstream * @short_description: Data Input Stream * @include: gio/gio.h @@ -15219,6 +15276,232 @@ /** + * g_datagram_based_condition_check: + * @datagram_based: a #GDatagramBased + * @condition: a #GIOCondition mask to check + * + * Checks on the readiness of @datagram_based to perform operations. The + * operations specified in @condition are checked for and masked against the + * currently-satisfied conditions on @datagram_based. The result is returned. + * + * %G_IO_IN will be set in the return value if data is available to read with + * g_datagram_based_receive_messages(), or if the connection is closed remotely + * (EOS); and if the datagram_based has not been closed locally using some + * implementation-specific method (such as g_socket_close() or + * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). + * + * If the connection is shut down or closed (by calling g_socket_close() or + * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for + * example), all calls to this function will return %G_IO_ERROR_CLOSED. + * + * %G_IO_OUT will be set if it is expected that at least one byte can be sent + * using g_datagram_based_send_messages() without blocking. It will not be set + * if the datagram_based has been closed locally. + * + * %G_IO_HUP will be set if the connection has been closed locally. + * + * %G_IO_ERR will be set if there was an asynchronous error in transmitting data + * previously enqueued using g_datagram_based_send_messages(). + * + * Note that on Windows, it is possible for an operation to return + * %G_IO_ERROR_WOULD_BLOCK even immediately after + * g_datagram_based_condition_check() has claimed that the #GDatagramBased is + * ready for writing. Rather than calling g_datagram_based_condition_check() and + * then writing to the #GDatagramBased if it succeeds, it is generally better to + * simply try writing right away, and try again later if the initial attempt + * returns %G_IO_ERROR_WOULD_BLOCK. + * + * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these + * conditions will always be set in the output if they are true. Apart from + * these flags, the output is guaranteed to be masked by @condition. + * + * This call never blocks. + * + * Returns: the #GIOCondition mask of the current state + * Since: 2.48 + */ + + +/** + * g_datagram_based_condition_wait: + * @datagram_based: a #GDatagramBased + * @condition: a #GIOCondition mask to wait for + * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 + * to block indefinitely + * @cancellable: (nullable): a #GCancellable + * @error: return location for a #GError + * + * Waits for up to @timeout microseconds for condition to become true on + * @datagram_based. If the condition is met, %TRUE is returned. + * + * If @cancellable is cancelled before the condition is met, or if @timeout is + * reached before the condition is met, then %FALSE is returned and @error is + * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). + * + * Returns: %TRUE if the condition was met, %FALSE otherwise + * Since: 2.48 + */ + + +/** + * g_datagram_based_create_source: + * @datagram_based: a #GDatagramBased + * @condition: a #GIOCondition mask to monitor + * @cancellable: (nullable): a #GCancellable + * + * Creates a #GSource that can be attached to a #GMainContext to monitor for + * the availability of the specified @condition on the #GDatagramBased. The + * #GSource keeps a reference to the @datagram_based. + * + * The callback on the source is of the #GDatagramBasedSourceFunc type. + * + * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these + * conditions will always be reported in the callback if they are true. + * + * If non-%NULL, @cancellable can be used to cancel the source, which will + * cause the source to trigger, reporting the current condition (which is + * likely 0 unless cancellation happened at the same time as a condition + * change). You can check for this in the callback using + * g_cancellable_is_cancelled(). + * + * Returns: (transfer full): a newly allocated #GSource + * Since: 2.48 + */ + + +/** + * g_datagram_based_receive_messages: + * @datagram_based: a #GDatagramBased + * @messages: (array length=num_messages): an array of #GInputMessage structs + * @num_messages: the number of elements in @messages + * @flags: an int containing #GSocketMsgFlags flags for the overall operation + * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 + * to block indefinitely + * @cancellable: (allow-none): a %GCancellable + * @error: return location for a #GError + * + * Receive one or more data messages from @datagram_based in one go. + * + * @messages must point to an array of #GInputMessage structs and + * @num_messages must be the length of this array. Each #GInputMessage + * contains a pointer to an array of #GInputVector structs describing the + * buffers that the data received in each message will be written to. + * + * @flags modify how all messages are received. 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. These + * flags affect the overall receive operation. Flags affecting individual + * messages are returned in #GInputMessage.flags. + * + * The other members of #GInputMessage are treated as described in its + * documentation. + * + * If @timeout is negative the call will block until @num_messages have been + * received, the connection is closed remotely (EOS), @cancellable is cancelled, + * or an error occurs. + * + * If @timeout is 0 the call will return up to @num_messages without blocking, + * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system + * to be received. + * + * If @timeout is positive the call will block on the same conditions as if + * @timeout were negative. If the timeout is reached + * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, + * otherwise it will return the number of messages received before timing out. + * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with + * recvmmsg().) + * + * To be notified when messages are available, wait for the %G_IO_IN condition. + * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from + * g_datagram_based_receive_messages() even if you were previously notified of a + * %G_IO_IN condition. + * + * If the remote peer closes the connection, any messages queued in the + * underlying receive buffer will be returned, and subsequent calls to + * g_datagram_based_receive_messages() will return 0 (with no error set). + * + * If the connection is shut down or closed (by calling g_socket_close() or + * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for + * example), all calls to this function will return %G_IO_ERROR_CLOSED. + * + * On error -1 is returned and @error is set accordingly. An error will only + * be returned if zero messages could be received; otherwise the number of + * messages successfully received before the error will be returned. If + * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any + * other error. + * + * Returns: number of messages received, or -1 on error. Note that the number + * of messages received may be smaller than @num_messages if @timeout is + * zero or positive, if the peer closed the connection, or if @num_messages + * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try + * to receive the remaining messages. + * Since: 2.48 + */ + + +/** + * g_datagram_based_send_messages: + * @datagram_based: a #GDatagramBased + * @messages: (array length=num_messages): an array of #GOutputMessage structs + * @num_messages: the number of elements in @messages + * @flags: an int containing #GSocketMsgFlags flags + * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 + * to block indefinitely + * @cancellable: (nullable): a %GCancellable + * @error: return location for a #GError + * + * Send one or more data messages from @datagram_based in one go. + * + * @messages must point to an array of #GOutputMessage structs and + * @num_messages must be the length of this array. Each #GOutputMessage + * contains an address to send the data to, and a pointer to an array of + * #GOutputVector structs to describe the buffers that the data to be sent + * for each message will be gathered from. + * + * @flags modify how the message is sent. 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. + * + * The other members of #GOutputMessage are treated as described in its + * documentation. + * + * If @timeout is negative the call will block until @num_messages have been + * sent, @cancellable is cancelled, or an error occurs. + * + * If @timeout is 0 the call will send up to @num_messages without blocking, + * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. + * + * If @timeout is positive the call will block on the same conditions as if + * @timeout were negative. If the timeout is reached before any messages are + * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number + * of messages sent before timing out. + * + * To be notified when messages can be sent, wait for the %G_IO_OUT condition. + * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from + * g_datagram_based_send_messages() even if you were previously notified of a + * %G_IO_OUT condition. (On Windows in particular, this is very common due to + * the way the underlying APIs work.) + * + * If the connection is shut down or closed (by calling g_socket_close() or + * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for + * example), all calls to this function will return %G_IO_ERROR_CLOSED. + * + * On error -1 is returned and @error is set accordingly. An error will only + * be returned if zero messages could be sent; otherwise the number of messages + * successfully sent before the error will be returned. If @cancellable is + * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. + * + * Returns: number of messages sent, or -1 on error. Note that the number of + * messages sent may be smaller than @num_messages if @timeout is zero + * or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in + * which case the caller may re-try to send the remaining messages. + * Since: 2.48 + */ + + +/** * g_dbus_action_group_get: * @connection: A #GDBusConnection * @bus_name: the bus name which exports the action group @@ -33949,6 +34232,23 @@ /** + * g_socket_connectable_to_string: + * @connectable: a #GSocketConnectable + * + * Format a #GSocketConnectable as a string. This is a human-readable format for + * use in debugging output, and is not a stable serialization format. It is not + * suitable for use in user interfaces as it exposes too much information for a + * user. + * + * If the #GSocketConnectable implementation does not support string formatting, + * the implementation’s type name will be returned as a fallback. + * + * Returns: (transfer full): the formatted string + * Since: 2.48 + */ + + +/** * g_socket_connection_connect: * @connection: a #GSocketConnection * @address: a #GSocketAddress specifying the remote address. |