Struct gio::Socket

#[repr(transparent)]
pub struct Socket { /* private fields */ }

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. glib::Object::new() you must call InitableExt::init() and check the results before using the object. This is done automatically in new() and 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 g_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.

Properties

blocking

Readable | Writeable

broadcast

Whether the socket should allow sending to broadcast addresses.

Readable | Writeable

family

Readable | Writeable | Construct Only

fd

Readable | Writeable | Construct Only

keepalive

Readable | Writeable

listen-backlog

Readable | Writeable

local-address

Readable

multicast-loopback

Whether outgoing multicast packets loop back to the local host.

Readable | Writeable

multicast-ttl

Time-to-live out outgoing multicast packets

Readable | Writeable

protocol

Readable | Writeable | Construct Only

remote-address

Readable

timeout

The timeout in seconds on socket I/O

Readable | Writeable

ttl

Time-to-live for outgoing unicast packets

Readable | Writeable

type

Readable | Writeable | Construct Only

Implements

SocketExt, glib::ObjectExt, DatagramBasedExt, InitableExt, SocketExtManual, DatagramBasedExtManual

Implementations

impl Socket

pub unsafe fn from_fd(fd: impl IntoRawFd) -> 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 g_object_unref().

pub unsafe fn from_socket(socket: impl IntoRawSocket) -> Result<Socket, Error>

impl Socket

pub const NONE: Option<&'static Socket> = None

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 g_object_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) -> Self

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 HasParamSpec for Socket

type ParamSpec = ParamSpecObject

type SetValue = Socket

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Socket>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Socket

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl Ord for Socket

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl ParentClassIs for Socket

type Parent = Object

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

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

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 StaticType for Socket

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Socket

impl IsA<DatagramBased> for Socket

impl IsA<Initable> for Socket