Trait gio::prelude::DatagramBasedExtManual

pub trait DatagramBasedExtManual:
    Sealed
    + IsA<DatagramBased>
    + Sized {
    // Provided methods
    fn create_source<F, C>(
        &self,
        condition: IOCondition,
        cancellable: Option<&C>,
        name: Option<&str>,
        priority: Priority,
        func: F,
    ) -> Source
       where F: FnMut(&Self, IOCondition) -> ControlFlow + 'static,
             C: IsA<Cancellable> { ... }
    fn create_source_future<C: IsA<Cancellable>>(
        &self,
        condition: IOCondition,
        cancellable: Option<&C>,
        priority: Priority,
    ) -> Pin<Box<dyn Future<Output = IOCondition> + 'static>> { ... }
    fn create_source_stream<C: IsA<Cancellable>>(
        &self,
        condition: IOCondition,
        cancellable: Option<&C>,
        priority: Priority,
    ) -> Pin<Box<dyn Stream<Item = IOCondition> + 'static>> { ... }
    fn condition_wait(
        &self,
        condition: IOCondition,
        timeout: Option<Duration>,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<(), Error> { ... }
    fn receive_messages<'v, V: IntoIterator<Item = &'v mut [&'v mut [u8]]>, C: IsA<Cancellable>>(
        &self,
        messages: &mut [InputMessage<'_>],
        flags: i32,
        timeout: Option<Duration>,
        cancellable: Option<&C>,
    ) -> Result<usize, Error> { ... }
    fn send_messages<C: IsA<Cancellable>>(
        &self,
        messages: &mut [OutputMessage<'_>],
        flags: i32,
        timeout: Option<Duration>,
        cancellable: Option<&C>,
    ) -> Result<usize, Error> { ... }
}

Provided Methods

fn create_source<F, C>( &self, condition: IOCondition, cancellable: Option<&C>, name: Option<&str>, priority: Priority, func: F, ) -> Source

where F: FnMut(&Self, IOCondition) -> ControlFlow + 'static, C: IsA<Cancellable>,

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 @self.

The callback on the source is of the #GDatagramBasedSourceFunc type.

It is meaningless to specify glib::IOCondition::ERR or glib::IOCondition::HUP in @condition; these conditions will always be reported in the callback if they are true.

If non-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 g_cancellable_is_cancelled().

condition

a #GIOCondition mask to monitor

cancellable

a #GCancellable

Returns

a newly allocated #GSource

fn create_source_future<C: IsA<Cancellable>>( &self, condition: IOCondition, cancellable: Option<&C>, priority: Priority, ) -> Pin<Box<dyn Future<Output = IOCondition> + 'static>>

fn create_source_stream<C: IsA<Cancellable>>( &self, condition: IOCondition, cancellable: Option<&C>, priority: Priority, ) -> Pin<Box<dyn Stream<Item = IOCondition> + 'static>>

fn condition_wait( &self, condition: IOCondition, timeout: Option<Duration>, cancellable: Option<&impl IsA<Cancellable>>, ) -> Result<(), Error>

Waits for up to @timeout microseconds for condition to become true on @self. 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 (IOErrorEnum::Cancelled or IOErrorEnum::TimedOut).

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

a #GCancellable

Returns

true if the condition was met, false otherwise

fn receive_messages<'v, V: IntoIterator<Item = &'v mut [&'v mut [u8]]>, C: IsA<Cancellable>>( &self, messages: &mut [InputMessage<'_>], flags: i32, timeout: Option<Duration>, cancellable: Option<&C>, ) -> Result<usize, Error>

Receive one or more data messages from @self 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 IOErrorEnum::WouldBlock 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, IOErrorEnum::TimedOut 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 glib::IOCondition::IN condition. Note though that you may still receive IOErrorEnum::WouldBlock from g_datagram_based_receive_messages() even if you were previously notified of a glib::IOCondition::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 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, IOErrorEnum::Cancelled is returned as with any other error.

messages

an array of #GInputMessage structs

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

a GCancellable

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.

fn send_messages<C: IsA<Cancellable>>( &self, messages: &mut [OutputMessage<'_>], flags: i32, timeout: Option<Duration>, cancellable: Option<&C>, ) -> Result<usize, Error>

Send one or more data messages from @self 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 IOErrorEnum::WouldBlock 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, IOErrorEnum::TimedOut 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 glib::IOCondition::OUT condition. Note though that you may still receive IOErrorEnum::WouldBlock from g_datagram_based_send_messages() even if you were previously notified of a glib::IOCondition::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 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, IOErrorEnum::Cancelled is returned as with any other error.

messages

an array of #GOutputMessage structs

flags

an int containing #GSocketMsgFlags flags

timeout

the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely

cancellable

a GCancellable

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.

Object Safety

This trait is not object safe.

Implementors

impl<O: IsA<DatagramBased>> DatagramBasedExtManual for O