Struct gio::Socket

pub struct Socket(_, _);

A Socket is a low-level networking primitive. It is a more or less direct mapping of the BSD socket API in a portable GObject based API. It supports both the UNIX socket implementations and winsock2 on Windows.

Socket is the platform independent base upon which the higher level network primitives are based. Applications are not typically meant to use it directly, but rather through classes like SocketClient, SocketService and SocketConnection. However there may be cases where direct use of Socket is useful.

Socket implements the Initable interface, so if it is manually constructed by e.g. gobject::Object::new you must call Initable::init and check the results before using the object. This is done automatically in Socket::new and Socket::new_from_fd, so these functions can return None.

Sockets operate in two general modes, blocking or non-blocking. When in blocking mode all operations (which don’t take an explicit blocking parameter) block until the requested operation is finished or there is an error. In non-blocking mode all calls that would block return immediately with a IOErrorEnum::WouldBlock error. To know when a call would successfully run you can call SocketExt::condition_check, or SocketExt::condition_wait. You can also use Socket::create_source and attach it to a glib::MainContext to get callbacks when I/O is possible. Note that all sockets are always set to non blocking mode in the system, and blocking mode is emulated in GSocket.

When working in non-blocking mode applications should always be able to handle getting a IOErrorEnum::WouldBlock error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write returns IOErrorEnum::WouldBlock.

GSockets can be either connection oriented or datagram based. For connection oriented types you must first establish a connection by either connecting to an address or accepting a connection from another address. For connectionless socket types the target/source address is specified or received in each I/O operation.

All socket file descriptors are set to be close-on-exec.

Note that creating a Socket causes the signal SIGPIPE to be ignored for the remainder of the program. If you are writing a command-line utility that uses Socket, you may need to take into account the fact that your program will not automatically be killed if it tries to write to stdout after it has been closed.

Like most other APIs in GLib, Socket is not inherently thread safe. To use a Socket concurrently from multiple threads, you must implement your own locking.

Implements

SocketExt, glib::object::ObjectExt, SocketExtManual

Methods

impl Socket

pub unsafe fn new_from_fd<T: IntoRawFd>(fd: T) -> Result<Socket, Error>

Creates a new Socket from a native file descriptor or winsock SOCKET handle.

This reads all the settings from the file descriptor so that all properties should work. Note that the file descriptor will be set to non-blocking mode, independent on the blocking mode of the Socket.

On success, the returned Socket takes ownership of fd. On failure, the caller must close fd themselves.

Since GLib 2.46, it is no longer a fatal error to call this on a non-socket descriptor. Instead, a GError will be set with code IOErrorEnum::Failed

fd

a native socket file descriptor.

Returns

a Socket or None on error. Free the returned object with gobject::ObjectExt::unref.

impl Socket

pub fn new(
    family: SocketFamily,
    type_: SocketType,
    protocol: SocketProtocol
) -> Result<Socket, Error>

Creates a new Socket with the defined family, type and protocol. If protocol is 0 (SocketProtocol::Default) the default protocol type for the family and type is used.

The protocol is a family and type specific int that specifies what kind of protocol to use. SocketProtocol lists several common ones. Many families only support one protocol, and use 0 for this, others support several and using 0 means to use the default protocol for the family and type.

The protocol id is passed directly to the operating system, so you can use protocols not listed in SocketProtocol if you know the protocol number used for it.

family

the socket family to use, e.g. SocketFamily::Ipv4.

type_

the socket type to use.

protocol

the id of the protocol to use, or 0 for default.

Returns

a Socket or None on error. Free the returned object with gobject::ObjectExt::unref.

Trait Implementations

impl AsRawFd for Socket

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Clone for Socket

fn clone(&self) -> Socket

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Socket

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Display for Socket

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Eq for Socket

impl Hash for Socket

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Ord for Socket

fn cmp(&self, other: &Socket) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use] fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use] fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use] fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: ObjectType> PartialEq<T> for Socket

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: ObjectType> PartialOrd<T> for Socket

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl SendUnique for Socket

fn is_unique(&self) -> bool

impl StaticType for Socket

fn static_type() -> Type

Returns the type identifier of Self.