Trait gio::prelude::SocketExtManual[−][src]

pub trait SocketExtManual: Sized {
    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_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_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 socket<T: FromRawSocket>(&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) -> 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>>;
}

Required methods

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

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

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

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

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

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

This is supported 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.

This is supported on Windows only.

Creates a glib::Source that can be attached to a GMainContext to monitor for the availability of the specified condition on the socket. The glib::Source keeps a reference to the self.

The callback on the source is of the GSocketSourceFunc type.

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

cancellable if not None 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().

If self has a timeout set, and it is reached before condition occurs, the source will then trigger anyway, reporting glib::IOCondition::IN or glib::IOCondition::OUT depending on condition. However, self will have been marked as having had a timeout, and so the next Socket I/O method you call will then fail with a IOErrorEnum::TimedOut.

condition

a glib::IOCondition mask to monitor

cancellable

a GCancellable or None

Returns

a newly allocated GSource, free with g_source_unref().

Implementors