:right-sidebar: True DatagramBased =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.48 .. class:: DatagramBased(*args, **kwargs) :no-contents-entry: Implementations: :class:`~gi.repository.Gio.Socket` Interface for socket-like objects with datagram semantics. 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 :obj:`~gi.repository.Gio.Socket`\, 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 :obj:`~gi.repository.Gio.IOStream`\. 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 :obj:`~gi.repository.Gio.DatagramBased.condition_check` or :obj:`~gi.repository.Gio.DatagramBased.condition_wait`\. You can also use :obj:`~gi.repository.Gio.DatagramBased.create_source` and attach it to a :obj:`~gi.repository.GLib.MainContext` 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``\, ``GDatagramBased``\s can be either connection oriented (for example, SCTP) or connectionless (for example, UDP). ``GDatagramBased``\s must be datagram-based, not stream-based. 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. Methods ------- .. rst-class:: interim-class .. class:: DatagramBased :no-index: .. method:: condition_check(condition: ~gi.repository.GLib.IOCondition) -> ~gi.repository.GLib.IOCondition 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 :func:`~gi.repository.Gio.DatagramBased.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 :func:`~gi.repository.Gio.Socket.close` or :func:`~gi.repository.Gio.Socket.shutdown` with ``shutdown_read`` set, if it’s a :obj:`~gi.repository.Gio.Socket`\). If the connection is shut down or closed (by calling :func:`~gi.repository.Gio.Socket.close` or :func:`~gi.repository.Gio.Socket.shutdown` with ``shutdown_read`` set, if it’s a :obj:`~gi.repository.Gio.Socket`\, for example), all calls to this function will return :const:`~gi.repository.Gio.IOErrorEnum.CLOSED`. %G_IO_OUT will be set if it is expected that at least one byte can be sent using :func:`~gi.repository.Gio.DatagramBased.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 :func:`~gi.repository.Gio.DatagramBased.send_messages`. Note that on Windows, it is possible for an operation to return :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` even immediately after :func:`~gi.repository.Gio.DatagramBased.condition_check` has claimed that the :obj:`~gi.repository.Gio.DatagramBased` is ready for writing. Rather than calling :func:`~gi.repository.Gio.DatagramBased.condition_check` and then writing to the :obj:`~gi.repository.Gio.DatagramBased` if it succeeds, it is generally better to simply try writing right away, and try again later if the initial attempt returns :const:`~gi.repository.Gio.IOErrorEnum.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. .. versionadded:: 2.48 :param condition: a :obj:`~gi.repository.GLib.IOCondition` mask to check .. method:: condition_wait(condition: ~gi.repository.GLib.IOCondition, timeout: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> bool Waits for up to ``timeout`` microseconds for condition to become true on ``datagram_based``\. If the condition is met, :const:`True` is returned. If ``cancellable`` is cancelled before the condition is met, or if ``timeout`` is reached before the condition is met, then :const:`False` is returned and ``error`` is set appropriately (:const:`~gi.repository.Gio.IOErrorEnum.CANCELLED` or :const:`~gi.repository.Gio.IOErrorEnum.TIMED_OUT`). .. versionadded:: 2.48 :param condition: a :obj:`~gi.repository.GLib.IOCondition` mask to wait for :param timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: create_source(condition: ~gi.repository.GLib.IOCondition, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GLib.Source Creates a :obj:`~gi.repository.GLib.Source` that can be attached to a :obj:`~gi.repository.GLib.MainContext` to monitor for the availability of the specified ``condition`` on the :obj:`~gi.repository.Gio.DatagramBased`\. The :obj:`~gi.repository.GLib.Source` 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-:const:`None`, ``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 :func:`~gi.repository.Gio.Cancellable.is_cancelled`. .. versionadded:: 2.48 :param condition: a :obj:`~gi.repository.GLib.IOCondition` mask to monitor :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: receive_messages(messages: list[~gi.repository.Gio.InputMessage], flags: int, timeout: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> int Receive one or more data messages from ``datagram_based`` in one go. ``messages`` must point to an array of :obj:`~gi.repository.Gio.InputMessage` structs and ``num_messages`` must be the length of this array. Each :obj:`~gi.repository.Gio.InputMessage` contains a pointer to an array of :obj:`~gi.repository.Gio.InputVector` 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 :obj:`~gi.repository.Gio.InputMessage`\.flags. The other members of :obj:`~gi.repository.Gio.InputMessage` 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 :const:`~gi.repository.Gio.IOErrorEnum.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, :const:`~gi.repository.Gio.IOErrorEnum.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 :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` from :func:`~gi.repository.Gio.DatagramBased.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 :func:`~gi.repository.Gio.DatagramBased.receive_messages` will return 0 (with no error set). If the connection is shut down or closed (by calling :func:`~gi.repository.Gio.Socket.close` or :func:`~gi.repository.Gio.Socket.shutdown` with ``shutdown_read`` set, if it’s a :obj:`~gi.repository.Gio.Socket`\, for example), all calls to this function will return :const:`~gi.repository.Gio.IOErrorEnum.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, :const:`~gi.repository.Gio.IOErrorEnum.CANCELLED` is returned as with any other error. .. versionadded:: 2.48 :param messages: an array of :obj:`~gi.repository.Gio.InputMessage` structs :param flags: an int containing ``GSocketMsgFlags`` flags for the overall operation :param timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely :param cancellable: a %GCancellable .. method:: send_messages(messages: list[~gi.repository.Gio.OutputMessage], flags: int, timeout: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> int Send one or more data messages from ``datagram_based`` in one go. ``messages`` must point to an array of :obj:`~gi.repository.Gio.OutputMessage` structs and ``num_messages`` must be the length of this array. Each :obj:`~gi.repository.Gio.OutputMessage` contains an address to send the data to, and a pointer to an array of :obj:`~gi.repository.Gio.OutputVector` 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 :obj:`~gi.repository.Gio.OutputMessage` 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 :const:`~gi.repository.Gio.IOErrorEnum.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, :const:`~gi.repository.Gio.IOErrorEnum.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 :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` from :func:`~gi.repository.Gio.DatagramBased.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 :func:`~gi.repository.Gio.Socket.close` or :func:`~gi.repository.Gio.Socket.shutdown` with ``shutdown_write`` set, if it’s a :obj:`~gi.repository.Gio.Socket`\, for example), all calls to this function will return :const:`~gi.repository.Gio.IOErrorEnum.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, :const:`~gi.repository.Gio.IOErrorEnum.CANCELLED` is returned as with any other error. .. versionadded:: 2.48 :param messages: an array of :obj:`~gi.repository.Gio.OutputMessage` structs :param flags: an int containing ``GSocketMsgFlags`` flags :param timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely :param cancellable: a %GCancellable Virtual Methods --------------- .. rst-class:: interim-class .. class:: DatagramBased :no-index: .. method:: do_condition_check(condition: ~gi.repository.GLib.IOCondition) -> ~gi.repository.GLib.IOCondition 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 :func:`~gi.repository.Gio.DatagramBased.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 :func:`~gi.repository.Gio.Socket.close` or :func:`~gi.repository.Gio.Socket.shutdown` with ``shutdown_read`` set, if it’s a :obj:`~gi.repository.Gio.Socket`\). If the connection is shut down or closed (by calling :func:`~gi.repository.Gio.Socket.close` or :func:`~gi.repository.Gio.Socket.shutdown` with ``shutdown_read`` set, if it’s a :obj:`~gi.repository.Gio.Socket`\, for example), all calls to this function will return :const:`~gi.repository.Gio.IOErrorEnum.CLOSED`. %G_IO_OUT will be set if it is expected that at least one byte can be sent using :func:`~gi.repository.Gio.DatagramBased.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 :func:`~gi.repository.Gio.DatagramBased.send_messages`. Note that on Windows, it is possible for an operation to return :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` even immediately after :func:`~gi.repository.Gio.DatagramBased.condition_check` has claimed that the :obj:`~gi.repository.Gio.DatagramBased` is ready for writing. Rather than calling :func:`~gi.repository.Gio.DatagramBased.condition_check` and then writing to the :obj:`~gi.repository.Gio.DatagramBased` if it succeeds, it is generally better to simply try writing right away, and try again later if the initial attempt returns :const:`~gi.repository.Gio.IOErrorEnum.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. .. versionadded:: 2.48 :param condition: a :obj:`~gi.repository.GLib.IOCondition` mask to check .. method:: do_condition_wait(condition: ~gi.repository.GLib.IOCondition, timeout: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> bool Waits for up to ``timeout`` microseconds for condition to become true on ``datagram_based``\. If the condition is met, :const:`True` is returned. If ``cancellable`` is cancelled before the condition is met, or if ``timeout`` is reached before the condition is met, then :const:`False` is returned and ``error`` is set appropriately (:const:`~gi.repository.Gio.IOErrorEnum.CANCELLED` or :const:`~gi.repository.Gio.IOErrorEnum.TIMED_OUT`). .. versionadded:: 2.48 :param condition: a :obj:`~gi.repository.GLib.IOCondition` mask to wait for :param timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: do_create_source(condition: ~gi.repository.GLib.IOCondition, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GLib.Source Creates a :obj:`~gi.repository.GLib.Source` that can be attached to a :obj:`~gi.repository.GLib.MainContext` to monitor for the availability of the specified ``condition`` on the :obj:`~gi.repository.Gio.DatagramBased`\. The :obj:`~gi.repository.GLib.Source` 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-:const:`None`, ``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 :func:`~gi.repository.Gio.Cancellable.is_cancelled`. .. versionadded:: 2.48 :param condition: a :obj:`~gi.repository.GLib.IOCondition` mask to monitor :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: do_receive_messages(messages: list[~gi.repository.Gio.InputMessage], flags: int, timeout: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> int Receive one or more data messages from ``datagram_based`` in one go. ``messages`` must point to an array of :obj:`~gi.repository.Gio.InputMessage` structs and ``num_messages`` must be the length of this array. Each :obj:`~gi.repository.Gio.InputMessage` contains a pointer to an array of :obj:`~gi.repository.Gio.InputVector` 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 :obj:`~gi.repository.Gio.InputMessage`\.flags. The other members of :obj:`~gi.repository.Gio.InputMessage` 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 :const:`~gi.repository.Gio.IOErrorEnum.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, :const:`~gi.repository.Gio.IOErrorEnum.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 :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` from :func:`~gi.repository.Gio.DatagramBased.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 :func:`~gi.repository.Gio.DatagramBased.receive_messages` will return 0 (with no error set). If the connection is shut down or closed (by calling :func:`~gi.repository.Gio.Socket.close` or :func:`~gi.repository.Gio.Socket.shutdown` with ``shutdown_read`` set, if it’s a :obj:`~gi.repository.Gio.Socket`\, for example), all calls to this function will return :const:`~gi.repository.Gio.IOErrorEnum.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, :const:`~gi.repository.Gio.IOErrorEnum.CANCELLED` is returned as with any other error. .. versionadded:: 2.48 :param messages: an array of :obj:`~gi.repository.Gio.InputMessage` structs :param flags: an int containing ``GSocketMsgFlags`` flags for the overall operation :param timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely :param cancellable: a %GCancellable .. method:: do_send_messages(messages: list[~gi.repository.Gio.OutputMessage], flags: int, timeout: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> int Send one or more data messages from ``datagram_based`` in one go. ``messages`` must point to an array of :obj:`~gi.repository.Gio.OutputMessage` structs and ``num_messages`` must be the length of this array. Each :obj:`~gi.repository.Gio.OutputMessage` contains an address to send the data to, and a pointer to an array of :obj:`~gi.repository.Gio.OutputVector` 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 :obj:`~gi.repository.Gio.OutputMessage` 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 :const:`~gi.repository.Gio.IOErrorEnum.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, :const:`~gi.repository.Gio.IOErrorEnum.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 :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` from :func:`~gi.repository.Gio.DatagramBased.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 :func:`~gi.repository.Gio.Socket.close` or :func:`~gi.repository.Gio.Socket.shutdown` with ``shutdown_write`` set, if it’s a :obj:`~gi.repository.Gio.Socket`\, for example), all calls to this function will return :const:`~gi.repository.Gio.IOErrorEnum.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, :const:`~gi.repository.Gio.IOErrorEnum.CANCELLED` is returned as with any other error. .. versionadded:: 2.48 :param messages: an array of :obj:`~gi.repository.Gio.OutputMessage` structs :param flags: an int containing ``GSocketMsgFlags`` flags :param timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely :param cancellable: a %GCancellable