Trait gio::prelude::DatagramBasedExtManual

pub trait DatagramBasedExtManual: Sized {
    // Required 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) -> Continue + '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>;
}

Required Methods

fn create_source<F, C>( &self, condition: IOCondition, cancellable: Option<&C>, name: Option<&str>, priority: Priority, func: F ) -> Sourcewhere F: FnMut(&Self, IOCondition) -> Continue + 'static, C: IsA<Cancellable>,

Creates a glib::Source that can be attached to a glib::MainContext to monitor for the availability of the specified condition on the DatagramBased. The glib::Source 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 CancellableExt::is_cancelled().

condition

a glib::IOCondition mask to monitor

cancellable

a Cancellable

Returns

a newly allocated glib::Source

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 glib::IOCondition mask to wait for

timeout

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

cancellable

a Cancellable

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 InputMessage structs and num_messages must be the length of this array. Each InputMessage 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 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 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 DatagramBasedExtManual::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 DatagramBasedExtManual::receive_messages() will return 0 (with no error set).

If the connection is shut down or closed (by calling SocketExt::close() or SocketExt::shutdown() with shutdown_read set, if it’s a Socket, 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 InputMessage 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 OutputMessage structs and num_messages must be the length of this array. Each OutputMessage 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 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 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 DatagramBasedExtManual::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 SocketExt::close() or SocketExt::shutdown() with shutdown_write set, if it’s a Socket, 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 OutputMessage 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.

Implementors

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