Struct GnsSocket 

pub struct GnsSocket<S> { /* private fields */ }

A network socket, and the main type of this library.

Use GnsSocket::connect to create a client socket and GnsSocket::listen to create a server socket. Every operation on a socket is safe.

Dropping a socket frees everything that belongs to it. It does not free the GnsGlobal instance.

Implementations

impl<S> GnsSocket<S>

where S: IsReady,

pub fn get_connection_real_time_status( &self, GnsConnection: GnsConnection, nb_of_lanes: u32, ) -> GnsResult<(GnsConnectionRealTimeStatus, Vec<GnsConnectionRealTimeLaneStatus>)>

Returns the status of a connection and of its lanes.

Configure the lanes with Self::configure_connection_lanes before you call this.

pub fn get_connection_info( &self, GnsConnection: GnsConnection, ) -> Option<GnsConnectionInfo>

pub fn get_detailed_connection_status( &self, GnsConnection: GnsConnection, ) -> Option<String>

Returns a verbose human-readable description of the state of a connection, intended for diagnostics and debug dumps.

The format is subject to change between GameNetworkingSockets versions, so do not parse it. Returns None if the connection handle is invalid.

pub fn get_connection_name( &self, GnsConnection: GnsConnection, ) -> Option<String>

Returns the debug name of a connection, previously set with Self::set_connection_name.

Returns None if the connection handle is invalid.

pub fn set_connection_name( &self, GnsConnection: GnsConnection, name: &str, ) -> GnsResult<()>

Sets the debug name of a connection.

The name shows up in diagnostics such as Self::get_detailed_connection_status and the debug output, which makes multi-connection logs much easier to read.

Errors

Returns GnsError::Config if name contains an interior NUL byte.

pub fn flush_messages_on_connection( &self, GnsConnection: GnsConnection, ) -> GnsResult<()>

pub fn close_connection( &self, GnsConnection: GnsConnection, reason: u32, debug: Option<&CStr>, linger: bool, ) -> GnsResult<()>

Closes a connection.

The wrapper forwards debug to the peer when you pass Some. Pass None to send no diagnostic string and avoid allocating.

Errors

Returns GnsError::Close if the connection handle is invalid, for example because the connection is already closed.

pub fn receive_messages<const K: usize>(&self) -> GnsResult<ReceivedMessages<K>>

Receives up to K messages and returns an iterator over the ones that were available.

Each message is yielded by value, so you can keep it, forward it, or let it drop, which releases it. Any message left in the iterator is released when the iterator is dropped.

The K-slot pointer buffer lives inline in the returned iterator, so this call allocates nothing and copies no payload. Use receive_messages_into to reuse one buffer across calls and avoid moving the inline array.

Errors

Returns GnsError::Receive if the connection or poll group handle is invalid.

pub fn receive_messages_into<'a>( &self, buffer: &'a mut [MessageSlot], ) -> GnsResult<ReceivedMessagesInto<'a>>

Receives up to buffer.len() messages into a buffer you own, and returns an iterator over the ones that were available.

This is the variant of receive_messages that neither allocates nor moves the buffer. GameNetworkingSockets fills buffer in place and the returned iterator borrows it, so reusing one buffer across a polling loop costs nothing per call.

Errors

Returns GnsError::Receive if the connection or poll group handle is invalid.

pub fn receive_events(&self) -> impl Iterator<Item = GnsConnectionEvent> + '_

Returns an iterator that drains the pending connection events.

Unlike receive_messages, you supply no buffer. Events arrive on an internal lock-free queue that the connection-status callback fills, and this call pops from that queue.

pub fn configure_connection_lanes( &self, GnsConnection: GnsConnection, lanes: &[GnsLane], ) -> GnsResult<()>

pub fn send_message( &self, message: GnsNetworkMessage<ToSend>, ) -> GnsResult<GnsMessageNumber>

Sends a single message to its target connection.

This is a convenience wrapper over send_messages for the common one-message case.

pub fn send_messages( &self, messages: impl IntoIterator<Item = GnsNetworkMessage<ToSend>>, ) -> Vec<SendOutcome>

Sends each message to its target connection.

The returned Vec holds one SendOutcome per input message, in the same order.

impl GnsSocket<IsCreated>

pub fn new(global: &'static GnsGlobal) -> Self

Creates a socket in the IsCreated state.

pub fn listen( self, address: IpAddr, port: u16, ) -> GnsResult<GnsSocket<IsServer>>

Listens for incoming connections.

This moves the socket from IsCreated to IsServer, which gives you the server operations.

pub fn connect( self, address: IpAddr, port: u16, ) -> GnsResult<GnsSocket<IsClient>>

Connects to a remote host.

This moves the socket from IsCreated to IsClient, which gives you the client operations.

pub fn socket_pair( self, use_network_loopback: bool, ) -> GnsResult<(GnsSocket<IsClient>, GnsSocket<IsClient>)>

Creates a pair of connections that talk to each other, mainly for tests and loopback communication between parts of one process.

With use_network_loopback set, the traffic goes through the local network stack over 127.0.0.1. Without it, the payloads take an internal shortcut. See ISteamNetworkingSockets::CreateSocketPair for the trade-offs.

Both sockets come back in the IsClient state and already connected. The connections are created before the wrapper can attach its connection-state callback, so the initial transition to the connected state never shows up in GnsSocket::receive_events. Later events, such as the peer closing the connection, are delivered normally.

impl GnsSocket<IsServer>

pub fn accept(&self, connection: GnsConnection) -> GnsResult<()>

Accepts an incoming connection. Only a socket in the IsServer state has this operation.

pub fn get_listen_socket_address(&self) -> Option<(IpAddr, u16)>

Returns the address the listen socket is bound to.

The address part is the unspecified address when the socket listens on every interface, which is what an all-zeros IP passed to GnsSocket::listen requests.

pub fn set_listen_socket_config_value( &self, typ: ESteamNetworkingConfigValue, value: GnsConfig<'_>, ) -> GnsResult<()>

Sets a configuration value on the listen socket, for example a connection option that every accepted connection inherits as its default.

pub fn get_listen_socket_config_value( &self, typ: ESteamNetworkingConfigValue, ) -> GnsResult<GnsConfigValue>

Reads a configuration value back from the listen socket.

impl GnsSocket<IsClient>

pub fn connection(&self) -> GnsConnection

Returns the socket connection. Only a socket in the IsClient state has this operation.