Trait gio::prelude::SocketExtManual

pub trait SocketExtManual: Sealed + IsA<Socket> + Sized {
    // Provided methods
    fn receive<B: AsMut<[u8]>, C: IsA<Cancellable>>(
        &self,
        buffer: B,
        cancellable: Option<&C>
    ) -> Result<usize, Error> { ... }
    fn receive_from<B: AsMut<[u8]>, C: IsA<Cancellable>>(
        &self,
        buffer: B,
        cancellable: Option<&C>
    ) -> Result<(usize, SocketAddress), Error> { ... }
    fn receive_message<C: IsA<Cancellable>>(
        &self,
        address: Option<&mut Option<SocketAddress>>,
        vectors: &mut [InputVector<'_>],
        control_messages: Option<&mut SocketControlMessages>,
        flags: i32,
        cancellable: Option<&C>
    ) -> Result<(usize, i32), Error> { ... }
    fn receive_messages<C: IsA<Cancellable>>(
        &self,
        messages: &mut [InputMessage<'_>],
        flags: i32,
        cancellable: Option<&C>
    ) -> Result<usize, Error> { ... }
    fn receive_with_blocking<B: AsMut<[u8]>, C: IsA<Cancellable>>(
        &self,
        buffer: B,
        blocking: bool,
        cancellable: Option<&C>
    ) -> Result<usize, Error> { ... }
    fn send<B: AsRef<[u8]>, C: IsA<Cancellable>>(
        &self,
        buffer: B,
        cancellable: Option<&C>
    ) -> Result<usize, Error> { ... }
    fn send_message<P: IsA<SocketAddress>, C: IsA<Cancellable>>(
        &self,
        address: Option<&P>,
        vectors: &[OutputVector<'_>],
        messages: &[SocketControlMessage],
        flags: i32,
        cancellable: Option<&C>
    ) -> Result<usize, Error> { ... }
    fn send_message_with_timeout<P: IsA<SocketAddress>, C: IsA<Cancellable>>(
        &self,
        address: Option<&P>,
        vectors: &[OutputVector<'_>],
        messages: &[SocketControlMessage],
        flags: i32,
        timeout: Option<Duration>,
        cancellable: Option<&C>
    ) -> Result<(PollableReturn, usize), Error> { ... }
    fn send_messages<C: IsA<Cancellable>>(
        &self,
        messages: &mut [OutputMessage<'_>],
        flags: i32,
        cancellable: Option<&C>
    ) -> Result<usize, Error> { ... }
    fn send_to<B: AsRef<[u8]>, P: IsA<SocketAddress>, C: IsA<Cancellable>>(
        &self,
        address: Option<&P>,
        buffer: B,
        cancellable: Option<&C>
    ) -> Result<usize, Error> { ... }
    fn send_with_blocking<B: AsRef<[u8]>, C: IsA<Cancellable>>(
        &self,
        buffer: B,
        blocking: bool,
        cancellable: Option<&C>
    ) -> Result<usize, Error> { ... }
    fn fd<T: FromRawFd>(&self) -> T { ... }
    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>> { ... }
}

Provided Methods

fn receive<B: AsMut<[u8]>, C: IsA<Cancellable>>( &self, buffer: B, cancellable: Option<&C> ) -> Result<usize, Error>

Receive data (up to size bytes) from a socket. This is mainly used by connection-oriented sockets; it is identical to SocketExtManual::receive_from() with address set to None.

For SocketType::Datagram and SocketType::Seqpacket sockets, SocketExtManual::receive() will always read either 0 or 1 complete messages from the socket. If the received message is too large to fit in buffer, then the data beyond size bytes will be discarded, without any explicit indication that this has occurred.

For SocketType::Stream sockets, SocketExtManual::receive() can return any number of bytes, up to size. If more than size bytes have been received, the additional data will be returned in future calls to SocketExtManual::receive().

If the socket is in blocking mode the call will block until there is some data to receive, the connection is closed, or there is an error. If there is no data available and the socket is in non-blocking mode, a IOErrorEnum::WouldBlock error will be returned. To be notified when data is available, wait for the glib::IOCondition::IN condition.

On error -1 is returned and error is set accordingly.

cancellable

a GCancellable or None

Returns

Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error

buffer

a buffer to read data into (which should be at least size bytes long).

fn receive_from<B: AsMut<[u8]>, C: IsA<Cancellable>>( &self, buffer: B, cancellable: Option<&C> ) -> Result<(usize, SocketAddress), Error>

Receive data (up to size bytes) from a socket.

If address is non-None then address will be set equal to the source address of the received packet. address is owned by the caller.

See SocketExtManual::receive() for additional information.

cancellable

a GCancellable or None

Returns

Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error

address

a pointer to a SocketAddress pointer, or None

buffer

a buffer to read data into (which should be at least size bytes long).

fn receive_message<C: IsA<Cancellable>>( &self, address: Option<&mut Option<SocketAddress>>, vectors: &mut [InputVector<'_>], control_messages: Option<&mut SocketControlMessages>, flags: i32, cancellable: Option<&C> ) -> Result<(usize, i32), Error>

Receive data from a socket. For receiving multiple messages, see SocketExtManual::receive_messages(); for easier use, see SocketExtManual::receive() and SocketExtManual::receive_from().

If address is non-None then address will be set equal to the source address of the received packet. address is owned by the caller.

vector must point to an array of GInputVector structs and num_vectors must be the length of this array. These structs describe the buffers that received data will be scattered into. If num_vectors is -1, then vectors is assumed to be terminated by a GInputVector with a None buffer pointer.

As a special case, if num_vectors is 0 (in which case, vectors may of course be None), then a single byte is received and discarded. This is to facilitate the common practice of sending a single ‘\0’ byte for the purposes of transferring ancillary data.

messages, if non-None, will be set to point to a newly-allocated array of SocketControlMessage instances or None if no such messages was received. These correspond to the control messages received from the kernel, one SocketControlMessage per message from the kernel. This array is None-terminated and must be freed by the caller using g_free() after calling g_object_unref() on each element. If messages is None, any control messages received will be discarded.

num_messages, if non-None, will be set to the number of control messages received.

If both messages and num_messages are non-None, then num_messages gives the number of SocketControlMessage instances in messages (ie: not including the None terminator).

flags is an in/out parameter. 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 (and SocketExtManual::receive_message() may pass system-specific flags out). Flags passed in to the parameter affect the receive operation; flags returned out of it are relevant to the specific returned message.

As with SocketExtManual::receive(), data may be discarded if self is SocketType::Datagram or SocketType::Seqpacket and you do not provide enough buffer space to read a complete message. You can pass G_SOCKET_MSG_PEEK in flags to peek at the current message without removing it from the receive queue, but there is no portable way to find out the length of the message other than by reading it into a sufficiently-large buffer.

If the socket is in blocking mode the call will block until there is some data to receive, the connection is closed, or there is an error. If there is no data available and the socket is in non-blocking mode, a IOErrorEnum::WouldBlock error will be returned. To be notified when data is available, wait for the glib::IOCondition::IN condition.

On error -1 is returned and error is set accordingly.

vectors

an array of GInputVector structs

flags

a pointer to an int containing GSocketMsgFlags flags, which may additionally contain other platform specific flags

cancellable

a GCancellable or None

Returns

Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error

address

a pointer to a SocketAddress pointer, or None

messages

a pointer which may be filled with an array of GSocketControlMessages, or None

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

Receive multiple data messages from self in one go. This is the most complicated and fully-featured version of this call. For easier use, see SocketExtManual::receive(), SocketExtManual::receive_from(), and SocketExtManual::receive_message().

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. Using multiple GInputVectors is more memory-efficient than manually copying data out of a single buffer to multiple sources, and more system-call-efficient than making multiple calls to SocketExtManual::receive(), such as in scenarios where a lot of data packets need to be received (e.g. high-bandwidth video streaming over RTP/UDP).

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 blocking is true the call will block until num_messages have been received, or the end of the stream is reached.

If blocking is false 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.

In blocking mode, if timeout is positive and is reached before any messages are received, IOErrorEnum::TimedOut is returned, otherwise up to num_messages are returned. (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 SocketExtManual::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 operating system will be returned, and subsequent calls to SocketExtManual::receive_messages() will return 0 (with no error set).

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.

messages

an array of InputMessage structs

flags

an int containing GSocketMsgFlags flags for the overall operation, which may additionally contain other platform specific flags

cancellable

a GCancellable or None

Returns

number of messages received, or -1 on error. Note that the number of messages received may be smaller than num_messages if in non-blocking mode, 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 receive_with_blocking<B: AsMut<[u8]>, C: IsA<Cancellable>>( &self, buffer: B, blocking: bool, cancellable: Option<&C> ) -> Result<usize, Error>

This behaves exactly the same as SocketExtManual::receive(), except that the choice of blocking or non-blocking behavior is determined by the blocking argument rather than by self’s properties.

blocking

whether to do blocking or non-blocking I/O

cancellable

a GCancellable or None

Returns

Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error

buffer

a buffer to read data into (which should be at least size bytes long).

fn send<B: AsRef<[u8]>, C: IsA<Cancellable>>( &self, buffer: B, cancellable: Option<&C> ) -> Result<usize, Error>

Tries to send size bytes from buffer on the socket. This is mainly used by connection-oriented sockets; it is identical to SocketExtManual::send_to() with address set to None.

If the socket is in blocking mode the call will block until there is space for the data in the socket queue. If there is no space available and the socket is in non-blocking mode a IOErrorEnum::WouldBlock error will be returned. To be notified when space is available, wait for the glib::IOCondition::OUT condition. Note though that you may still receive IOErrorEnum::WouldBlock from SocketExtManual::send() 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.)

On error -1 is returned and error is set accordingly.

buffer

the buffer containing the data to send.

cancellable

a GCancellable or None

Returns

Number of bytes written (which may be less than size), or -1 on error

fn send_message<P: IsA<SocketAddress>, C: IsA<Cancellable>>( &self, address: Option<&P>, vectors: &[OutputVector<'_>], messages: &[SocketControlMessage], flags: i32, cancellable: Option<&C> ) -> Result<usize, Error>

Send data to address on self. For sending multiple messages see SocketExtManual::send_messages(); for easier use, see SocketExtManual::send() and SocketExtManual::send_to().

If address is None then the message is sent to the default receiver (set by SocketExt::connect()).

vectors must point to an array of GOutputVector structs and num_vectors must be the length of this array. (If num_vectors is -1, then vectors is assumed to be terminated by a GOutputVector with a None buffer pointer.) The GOutputVector structs describe the buffers that the sent data will be gathered from. Using multiple GOutputVectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to SocketExtManual::send().

messages, if non-None, is taken to point to an array of num_messages SocketControlMessage instances. These correspond to the control messages to be sent on the socket. If num_messages is -1 then messages is treated as a None-terminated array.

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.

If the socket is in blocking mode the call will block until there is space for the data in the socket queue. If there is no space available and the socket is in non-blocking mode a IOErrorEnum::WouldBlock error will be returned. To be notified when space is available, wait for the glib::IOCondition::OUT condition. Note though that you may still receive IOErrorEnum::WouldBlock from SocketExtManual::send() 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.)

The sum of the sizes of each GOutputVector in vectors must not be greater than G_MAXSSIZE. If the message can be larger than this, then it is mandatory to use the SocketExtManual::send_message_with_timeout() function.

On error -1 is returned and error is set accordingly.

address

a SocketAddress, or None

vectors

an array of GOutputVector structs

messages

a pointer to an array of GSocketControlMessages, or None.

flags

an int containing GSocketMsgFlags flags, which may additionally contain other platform specific flags

cancellable

a GCancellable or None

Returns

Number of bytes written (which may be less than size), or -1 on error

fn send_message_with_timeout<P: IsA<SocketAddress>, C: IsA<Cancellable>>( &self, address: Option<&P>, vectors: &[OutputVector<'_>], messages: &[SocketControlMessage], flags: i32, timeout: Option<Duration>, cancellable: Option<&C> ) -> Result<(PollableReturn, usize), Error>

Available on crate feature v2_60 only.

This behaves exactly the same as SocketExtManual::send_message(), except that the choice of timeout behavior is determined by the timeout_us argument rather than by self’s properties.

On error PollableReturn::Failed is returned and error is set accordingly, or if the socket is currently not writable PollableReturn::WouldBlock is returned. bytes_written will contain 0 in both cases.

address

a SocketAddress, or None

vectors

an array of GOutputVector structs

messages

a pointer to an array of GSocketControlMessages, or None.

flags

an int containing GSocketMsgFlags flags, which may additionally contain other platform specific flags

timeout_us

the maximum time (in microseconds) to wait, or -1

cancellable

a GCancellable or None

Returns

PollableReturn::Ok if all data was successfully written, PollableReturn::WouldBlock if the socket is currently not writable, or PollableReturn::Failed if an error happened and error is set.

bytes_written

location to store the number of bytes that were written to the socket

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

Send multiple data messages from self in one go. This is the most complicated and fully-featured version of this call. For easier use, see SocketExtManual::send(), SocketExtManual::send_to(), and SocketExtManual::send_message().

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. Using multiple GOutputVectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to SocketExtManual::send(). Sending multiple messages in one go avoids the overhead of making a lot of syscalls in scenarios where a lot of data packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), or where the same data needs to be sent to multiple recipients.

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.

If the socket is in blocking mode the call will block until there is space for all the data in the socket queue. If there is no space available and the socket is in non-blocking mode a IOErrorEnum::WouldBlock error will be returned if no data was written at all, otherwise the number of messages sent will be returned. To be notified when space is available, wait for the glib::IOCondition::OUT condition. Note though that you may still receive IOErrorEnum::WouldBlock from SocketExtManual::send() 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.)

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.

messages

an array of OutputMessage structs

flags

an int containing GSocketMsgFlags flags, which may additionally contain other platform specific flags

cancellable

a GCancellable or None

Returns

number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than num_messages if the socket is non-blocking or if num_messages was larger than UIO_MAXIOV (1024), in which case the caller may re-try to send the remaining messages.

fn send_to<B: AsRef<[u8]>, P: IsA<SocketAddress>, C: IsA<Cancellable>>( &self, address: Option<&P>, buffer: B, cancellable: Option<&C> ) -> Result<usize, Error>

Tries to send size bytes from buffer to address. If address is None then the message is sent to the default receiver (set by SocketExt::connect()).

See SocketExtManual::send() for additional information.

address

a SocketAddress, or None

buffer

the buffer containing the data to send.

cancellable

a GCancellable or None

Returns

Number of bytes written (which may be less than size), or -1 on error

fn send_with_blocking<B: AsRef<[u8]>, C: IsA<Cancellable>>( &self, buffer: B, blocking: bool, cancellable: Option<&C> ) -> Result<usize, Error>

This behaves exactly the same as SocketExtManual::send(), except that the choice of blocking or non-blocking behavior is determined by the blocking argument rather than by self’s properties.

buffer

the buffer containing the data to send.

blocking

whether to do blocking or non-blocking I/O

cancellable

a GCancellable or None

Returns

Number of bytes written (which may be less than size), or -1 on error

fn fd<T: FromRawFd>(&self) -> T

Available on Unix only.

Returns the underlying OS socket object. On unix this is a socket file descriptor, and on Windows this is a Winsock2 SOCKET handle. This may be useful for doing platform specific or otherwise unusual operations on the socket.

Returns

the file descriptor of the socket.

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>>

Object Safety

This trait is not object safe.

Implementors

impl<O: IsA<Socket>> SocketExtManual for O