steamnet

Documentation

Overview

Package steamnet wraps Steam's peer-to-peer networking API.

This package works in both clients and servers.

See the Steam Networking documentation for more details. <https://partner.steamgames.com/doc/features/multiplayer/networking>

Index

• Variables
• func CloseAllChannels(user steamworks.SteamID) bool
• func CloseChannel(user steamworks.SteamID, channel int32) bool
• func Listen(accept func(steamworks.SteamID) bool) steamworks.Registration
• func ReadPacket(channel int32) ([]byte, steamworks.SteamID)
• func RegisterErrorCallback(f func(steamworks.SteamID, error)) steamworks.Registration
• func SendPacket(user steamworks.SteamID, data []byte, sendType Reliability, channel int32) error
• func SetAllowPacketRelay(allow bool)
• type Error
  • func (err Error) Error() string
  • func (err Error) Temporary() bool
  • func (err Error) Timeout() bool
• type Reliability
• type SessionState
  • func GetSessionState(user steamworks.SteamID) *SessionState

Variables

var (
	// ErrNotRunningApp is returned if the target user is not running the same
	// game.
	ErrNotRunningApp error = Error(internal.EP2PSessionError_NotRunningApp)
	// ErrNoRightsToApp is returned if the local user doesn't own the app that
	// is running.
	ErrNoRightsToApp error = Error(internal.EP2PSessionError_NoRightsToApp)
	// ErrDestinationNotLoggedIn is returned if the target user isn't connected
	// to Steam.
	ErrDestinationNotLoggedIn error = Error(internal.EP2PSessionError_DestinationNotLoggedIn)
	// ErrTimeout is returned if the connection timed out because the target
	// user didn't respond.
	ErrTimeout error = Error(internal.EP2PSessionError_Timeout)
)

var (
	ErrTargetUserInvalid = sendError{/* contains filtered or unexported fields */}
	ErrPacketTooLarge    = sendError{/* contains filtered or unexported fields */}
	ErrBufferFull        = sendError{/* contains filtered or unexported fields */}
)

Possible errors that can be returned by SendPacket.

Functions

func CloseAllChannels

func CloseAllChannels(user steamworks.SteamID) bool

CloseAllChannels should be called when you're done communicating with a user, as this will free up all of the resources allocated for the connection under-the-hood.

If the remote user tries to send data to you again, a new Listen callback will be posted.

Returns true if the session was successfully closed; otherwise, false if no connection was open with the user.

func CloseChannel

func CloseChannel(user steamworks.SteamID, channel int32) bool

CloseChannel closes a P2P channel when you're done talking to a user on the specific channel.

Once all channels to a user have been closed, the open session to the user will be closed and new data from this user will trigger a new Listen callback.

Returns true if the channel was successfully closed; otherwise, false if there was no active session or channel with the user.

func Listen

func Listen(accept func(steamworks.SteamID) bool) steamworks.Registration

Listen registers a function to handle connection requests.

The function will be called from the callback thread, and will cause the connection to be accepted if it returns true.

Multiple listeners may be registered simultaneously, and connections will be accepted if any listener returns true.

func ReadPacket

func ReadPacket(channel int32) ([]byte, steamworks.SteamID)

ReadPacket checks if a P2P packet is available and returns the packet if there is one.

This should be called in a loop for each channel that you use.

This call is non-blocking. It will return (nil, 0) if no data is available.

func RegisterErrorCallback

func RegisterErrorCallback(f func(steamworks.SteamID, error)) steamworks.Registration

RegisterErrorCallback registers a function to be called when packets can't get through to the specified user.

All queued packets unsent at this point will be dropped, further attempts to send will retry making the connection (but will be dropped if we fail again).

func SendPacket

func SendPacket(user steamworks.SteamID, data []byte, sendType Reliability, channel int32) error

SendPacket sends a P2P packet to the specified user.

This is a session-less API which automatically establishes NAT-traversing or Steam relay server connections.

The first packet send may be delayed as the NAT-traversal code runs.

See Reliability for descriptions of the different ways of sending packets.

The type of data you send is arbitrary, you can use an off the shelf system like Protocol Buffers or Cap'n Proto to encode your packets in an efficient way, or you can create your own messaging system.

Note that a nil return value does not mean the packet was successfully received. If the packet is not received after a timeout of 20 seconds, an error will be sent to the function registered with RegisterErrorCallback.

func SetAllowPacketRelay

func SetAllowPacketRelay(allow bool)

SetAllowPacketRelay allows or disallows P2P connections to fall back to being relayed through the Steam servers if a direct connection or NAT-traversal cannot be established.

This only applies to connections created after setting this value, or to existing connections that need to automatically reconnect after this value is set.

P2P packet relay is allowed by default.

Types

type Error

type Error internal.EP2PSessionError

Error represents a connection error in the Steam P2P API.

func (Error) Error

func (err Error) Error() string

func (Error) Temporary

func (err Error) Temporary() bool

Temporary returns true iff this error might go away after a retry with no other local actions.

func (Error) Timeout

func (err Error) Timeout() bool

Timeout returns true iff this error was caused by a timeout.

type Reliability

type Reliability = internal.EP2PSend

Reliability specifies the send type of SendPacket. Typically Unreliable is what you want for UDP-like packets, Reliable for TCP-like packets.

const (
	// Unreliable is a basic UDP send. Packets can't be bigger than 1200 bytes
	// (your typical MTU size). Can be lost, or arrive out of order (rare). The
	// sending API does have some knowledge of the underlying connection, so if
	// there is no NAT-traversal accomplished or there is a recognized
	// adjustment happening on the connection, the packet will be batched until
	// the connection is open again.
	Unreliable Reliability = internal.EP2PSend_Unreliable

	// UnreliableNoDelay works like Unreliable, but if the underlying P2P
	// connection isn't yet established the packet will just be thrown away.
	// Using this on the first packet sent to a remote host almost guarantees
	// the packet will be dropped. This is only really useful for kinds of data
	// that should never buffer up, e.g. voice payload packets
	UnreliableNoDelay Reliability = internal.EP2PSend_UnreliableNoDelay

	// Reliable message send. Can send up to 1MB of data in a single message.
	// Does fragmentation/re-assembly of messages under the hood, as well as a
	// sliding window for efficient sends of large chunks of data.
	Reliable Reliability = internal.EP2PSend_Reliable

	// ReliableWithBuffering works like Reliable, but applies the Nagle
	// algorithm to the send - sends will accumulate until the current MTU size
	// (typically ~1200 bytes, but can change) or ~200ms has passed (Nagle
	// algorithm). This is useful if you want to send a set of smaller messages
	// but have the coalesced into a single packet.
	//
	// Since the reliable stream is all ordered, you can do several small
	// message sends with ReliableWithBuffering and then do a normal Reliable
	// to force all the buffered data to be sent.
	ReliableWithBuffering Reliability = internal.EP2PSend_ReliableWithBuffering
)

type SessionState

type SessionState struct {
	// LastError recorded on the socket.
	LastError error
	// RemoteIP of the other end of the connection (if set). Could be a Steam
	// relay server. This only exists for compatibility with older
	// authentication APIs.
	RemoteIP net.IP
	// RemotePort of the other end of the connection (if set). Could be a Steam
	// relay server. This only exists for compatibility with older
	// authentication APIs.
	RemotePort int
	// BytesQueuedForSend is the number of bytes queued up to be sent to the
	// user.
	BytesQueuedForSend int
	// PacketsQueuedForSend is the number of packets queued up to be sent to
	// the user.
	PacketsQueuedForSend int
	// ConnectionActive is true if there is an open connection with the user.
	ConnectionActive bool
	// Connecting is true if we are currently trying to establish a connection
	// with the user.
	Connecting bool
	// UsingRelay is true if the connection is currently routed through a Steam
	// relay server.
	UsingRelay bool
}

SessionState is the current connection state to a specified user, returned by GetSessionState. This is the under-the-hood info about what's going on with a previous call to SendP2PPacket. This typically shouldn't be needed except for debugging purposes.

func GetSessionState

func GetSessionState(user steamworks.SteamID) *SessionState

GetSessionState returns a structure with details about the session like whether there is an active connection, the number of bytes queued on the connection, the last error code (if any), whether or not a relay server is being used, and the IP and Port of the remote user (if known).

This should only be needed for debugging purposes.

Returns nil if there was no open session with the specified user.