gio/auto/
datagram_based.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::ffi;
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// Interface for socket-like objects with datagram semantics.
10    ///
11    /// A `GDatagramBased` is a networking interface for representing datagram-based
12    /// communications. It is a more or less direct mapping of the core parts of the
13    /// BSD socket API in a portable GObject interface. It is implemented by
14    /// [`Socket`][crate::Socket], which wraps the UNIX socket API on UNIX and winsock2 on Windows.
15    ///
16    /// `GDatagramBased` is entirely platform independent, and is intended to be used
17    /// alongside higher-level networking APIs such as [`IOStream`][crate::IOStream].
18    ///
19    /// It uses vectored scatter/gather I/O by default, allowing for many messages
20    /// to be sent or received in a single call. Where possible, implementations of
21    /// the interface should take advantage of vectored I/O to minimise processing
22    /// or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()`
23    /// where possible. Callers should take advantage of scatter/gather I/O (the use of
24    /// multiple buffers per message) to avoid unnecessary copying of data to
25    /// assemble or disassemble a message.
26    ///
27    /// Each `GDatagramBased` operation has a timeout parameter which may be negative
28    /// for blocking behaviour, zero for non-blocking behaviour, or positive for
29    /// timeout behaviour. A blocking operation blocks until finished or there is an
30    /// error. A non-blocking operation will return immediately with a
31    /// `G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation
32    /// will block until the operation is complete or the timeout expires; if the
33    /// timeout expires it will return what progress it made, or
34    /// `G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would
35    /// successfully run you can call [`DatagramBasedExt::condition_check()`][crate::prelude::DatagramBasedExt::condition_check()] or
36    /// [`DatagramBasedExtManual::condition_wait()`][crate::prelude::DatagramBasedExtManual::condition_wait()]. You can also use
37    /// [`DatagramBasedExtManual::create_source()`][crate::prelude::DatagramBasedExtManual::create_source()] and attach it to a [`glib::MainContext`][crate::glib::MainContext]
38    /// to get callbacks when I/O is possible.
39    ///
40    /// When running a non-blocking operation applications should always be able to
41    /// handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function
42    /// said that I/O was possible. This can easily happen in case of a race
43    /// condition in the application, but it can also happen for other reasons. For
44    /// instance, on Windows a socket is always seen as writable until a write
45    /// returns `G_IO_ERROR_WOULD_BLOCK`.
46    ///
47    /// As with `GSocket`, `GDatagramBased`s can be either connection oriented (for
48    /// example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be
49    /// datagram-based, not stream-based. The interface does not cover connection
50    /// establishment — use methods on the underlying type to establish a connection
51    /// before sending and receiving data through the `GDatagramBased` API. For
52    /// connectionless socket types the target/source address is specified or
53    /// received in each I/O operation.
54    ///
55    /// Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe.
56    /// To use a `GDatagramBased` concurrently from multiple threads, you must
57    /// implement your own locking.
58    ///
59    /// # Implements
60    ///
61    /// [`DatagramBasedExt`][trait@crate::prelude::DatagramBasedExt], [`DatagramBasedExtManual`][trait@crate::prelude::DatagramBasedExtManual]
62    #[doc(alias = "GDatagramBased")]
63    pub struct DatagramBased(Interface<ffi::GDatagramBased, ffi::GDatagramBasedInterface>);
64
65    match fn {
66        type_ => || ffi::g_datagram_based_get_type(),
67    }
68}
69
70impl DatagramBased {
71    pub const NONE: Option<&'static DatagramBased> = None;
72}
73
74/// Trait containing all [`struct@DatagramBased`] methods.
75///
76/// # Implementors
77///
78/// [`DatagramBased`][struct@crate::DatagramBased], [`DtlsClientConnection`][struct@crate::DtlsClientConnection], [`DtlsConnection`][struct@crate::DtlsConnection], [`DtlsServerConnection`][struct@crate::DtlsServerConnection], [`Socket`][struct@crate::Socket]
79pub trait DatagramBasedExt: IsA<DatagramBased> + 'static {
80    /// Checks on the readiness of @self to perform operations. The
81    /// operations specified in @condition are checked for and masked against the
82    /// currently-satisfied conditions on @self. The result is returned.
83    ///
84    /// [`glib::IOCondition::IN`][crate::glib::IOCondition::IN] will be set in the return value if data is available to read with
85    /// g_datagram_based_receive_messages(), or if the connection is closed remotely
86    /// (EOS); and if the datagram_based has not been closed locally using some
87    /// implementation-specific method (such as g_socket_close() or
88    /// g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
89    ///
90    /// If the connection is shut down or closed (by calling g_socket_close() or
91    /// g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
92    /// example), all calls to this function will return [`IOErrorEnum::Closed`][crate::IOErrorEnum::Closed].
93    ///
94    /// [`glib::IOCondition::OUT`][crate::glib::IOCondition::OUT] will be set if it is expected that at least one byte can be sent
95    /// using g_datagram_based_send_messages() without blocking. It will not be set
96    /// if the datagram_based has been closed locally.
97    ///
98    /// [`glib::IOCondition::HUP`][crate::glib::IOCondition::HUP] will be set if the connection has been closed locally.
99    ///
100    /// [`glib::IOCondition::ERR`][crate::glib::IOCondition::ERR] will be set if there was an asynchronous error in transmitting data
101    /// previously enqueued using g_datagram_based_send_messages().
102    ///
103    /// Note that on Windows, it is possible for an operation to return
104    /// [`IOErrorEnum::WouldBlock`][crate::IOErrorEnum::WouldBlock] even immediately after
105    /// g_datagram_based_condition_check() has claimed that the #GDatagramBased is
106    /// ready for writing. Rather than calling g_datagram_based_condition_check() and
107    /// then writing to the #GDatagramBased if it succeeds, it is generally better to
108    /// simply try writing right away, and try again later if the initial attempt
109    /// returns [`IOErrorEnum::WouldBlock`][crate::IOErrorEnum::WouldBlock].
110    ///
111    /// It is meaningless to specify [`glib::IOCondition::ERR`][crate::glib::IOCondition::ERR] or [`glib::IOCondition::HUP`][crate::glib::IOCondition::HUP] in @condition; these
112    /// conditions will always be set in the output if they are true. Apart from
113    /// these flags, the output is guaranteed to be masked by @condition.
114    ///
115    /// This call never blocks.
116    /// ## `condition`
117    /// a #GIOCondition mask to check
118    ///
119    /// # Returns
120    ///
121    /// the #GIOCondition mask of the current state
122    #[doc(alias = "g_datagram_based_condition_check")]
123    fn condition_check(&self, condition: glib::IOCondition) -> glib::IOCondition {
124        unsafe {
125            from_glib(ffi::g_datagram_based_condition_check(
126                self.as_ref().to_glib_none().0,
127                condition.into_glib(),
128            ))
129        }
130    }
131}
132
133impl<O: IsA<DatagramBased>> DatagramBasedExt for O {}
gio/auto/datagram_based.rs

gio/auto/
datagram_based.rs
