Crate gns 

Rust wrapper for Valve GameNetworkingSockets

This crate wraps the low-level GameNetworkingSockets library and gives you two things:

• Type safety. The socket type records its own state, so the compiler rejects any operation that the current state does not allow. Every public operation is safe to call.
• A high-level API. You never write FFI code. The API is plain, idiomatic Rust.

Example

use gns::{GnsGlobal, GnsSocket, IsCreated};
use std::net::Ipv6Addr;
use std::time::Duration;

// Do not use `unwrap` in production. This example uses it to keep the
// interesting calls easy to read.

// Initialize the global networking state. A process has exactly one.
let gns_global = GnsGlobal::get().unwrap();

// Create a socket. The type parameter records the socket state, and
// `GnsSocket::new` is only available in the initial `IsCreated` state.
let gns_socket = GnsSocket::<IsCreated>::new(gns_global);

// Choose your own port.
let port = 9001;

// `connect` moves the socket from `IsCreated` to `IsClient`, which gives
// you the client operations.
let client = gns_socket.connect(Ipv6Addr::LOCALHOST.into(), port).unwrap();

// A connected socket needs three calls in your main loop:
//
// 1. Poll for new messages.
// 2. Poll for connection status changes.
// 3. Poll for the low-level callbacks that the underlying library needs.
//
// Clients and servers use the same three calls. Only the scope differs. On
// a client they cover the single connection. On a server they cover every
// connected client.

// Run the low-level callbacks.
gns_global.poll_callbacks();

// Receive at most 100 messages and print each payload.
for message in client.receive_messages::<100>().expect("failed to recv").into_iter() {
  println!("{}", core::str::from_utf8(message.payload()).unwrap());
}

// This example ignores events. A real program reads them to react when the
// connection opens or closes.
for _event in client.receive_events() {
}

// Wait before the next iteration.
std::thread::sleep(Duration::from_millis(10))

How events reach a socket

Each GnsSocket registers a weak reference to its event queue with GnsGlobal. When GameNetworkingSockets reports a connection-state change, the callback uses that registry to find the socket the event belongs to. Dropping the socket removes its entry.

Re-exports

pub use gns_sys as sys;

Structs

GnsConnection

GnsConnectionEvent

GnsConnectionInfo

GnsConnectionRealTimeLaneStatus

GnsConnectionRealTimeStatus

GnsGlobal

Owns the initialization and teardown of GameNetworkingSockets and its singletons.

GnsLane

A connection lane.

GnsNetworkMessage

A GameNetworkingSockets message, tagged with its direction.

GnsSocket

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

GnsUtils

IsClient

The state of a GnsSocket that acts as a client, normally reached through GnsSocket::connect.

IsCreated

The initial state of a GnsSocket.

IsServer

The state of a GnsSocket that acts as a server, normally reached through GnsSocket::listen.

ReceivedMessages

An iterator over the messages from one GnsSocket::receive_messages call.

ReceivedMessagesInto

An iterator returned by GnsSocket::receive_messages_into.

SendFlags

A type-safe wrapper over the k_nSteamNetworkingSend_* flags.

ToReceive

ToSend

Enums

GnsConfig

A configuration value for GnsUtils::set_global_config_value and GnsUtils::set_connection_config_value.

GnsConfigValue

A configuration value read back through GnsUtils::get_global_config_value and friends.

GnsError

An error returned by the wrapper.

SendOutcome

The result of one message in a GnsSocket::send_messages batch.

Traits

IsReady

The operations that every ready GnsSocket supports.

Payload

An owned byte buffer for an outbound message.

Type Aliases

GnsLaneId

A lane identifier.

GnsMessageNumber

A network message number. This alias exists to make signatures readable.

GnsResult

MessageSlot

A single receive slot.