Unaffiliated

Home Documentation & Help
Steamworks Documentation
ISteamNetworking Interface
Networking functions for making connections and sending data between clients, traversing NATs when possible.

See Steam Networking for more information.

Member Functions

Member functions for ISteamNetworking are called through the global accessor function SteamNetworking().

AcceptP2PSessionWithUser

bool AcceptP2PSessionWithUser( CSteamID steamIDRemote );
NameTypeDescription
steamIDRemoteCSteamIDThe Steam ID of the user that sent the initial packet to us.

This allows the game to specify accept an incoming packet. This needs to be called before a real connection is established to a remote host, the game will get a chance to say whether or not the remote user is allowed to talk to them.

When a remote user that you haven't sent a packet to recently, tries to first send you a packet, your game will receive a callback P2PSessionRequest_t. This callback contains the Steam ID of the user who wants to send you a packet. In response to this callback, you'll want to see if it's someone you want to talk to (for example, if they're in a lobby with you), and if so, accept the connection; otherwise if you don't want to talk to the user, just ignore the request. If the user continues to send you packets, another P2PSessionRequest_t will be posted periodically. If you've called SendP2PPacket on the other user, this implicitly accepts the session request.

Note that this call should only be made in response to a P2PSessionRequest_t callback!

Returns: bool
true upon success; false only if steamIDRemote is invalid.

AllowP2PPacketRelay

bool AllowP2PPacketRelay( bool bAllow );
NameTypeDescription
bAllowbool

Allow or disallow 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.

Returns: bool
This function always returns true.

CloseP2PChannelWithUser

bool CloseP2PChannelWithUser( CSteamID steamIDRemote, int nChannel );
NameTypeDescription
steamIDRemoteCSteamIDThe Steam ID of the user to close the connection with.
nChannelintThe channel to close.

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 P2PSessionRequest_t callback.

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

CloseP2PSessionWithUser

bool CloseP2PSessionWithUser( CSteamID steamIDRemote );
NameTypeDescription
steamIDRemoteCSteamIDThe Steam ID of the user to close the connection with.

This 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 P2PSessionRequest_t callback will be posted.

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

CreateConnectionSocket

SNetSocket_t CreateConnectionSocket( uint32 nIP, uint16 nPort, int nTimeoutSec );
NameTypeDescription
nIPuint32
nPortuint16
nTimeoutSecint

Creates a socket and begin connection to a remote destination.

This is part of an older set of functions designed around the Berkeley TCP sockets model. It's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: SNetSocket_t

CreateListenSocket

SNetListenSocket_t CreateListenSocket( int nVirtualP2PPort, uint32 nIP, uint16 nPort, bool bAllowUseOfPacketRelay );
NameTypeDescription
nVirtualP2PPortint
nIPuint32
nPortuint16
bAllowUseOfPacketRelaybool

Creates a socket and listens others to connect.

Will trigger a SocketStatusCallback_t callback on another client connecting.

nVirtualP2PPort is the unique ID that the client will connect to, in case you have multiple ports
this can usually just be 0 unless you want multiple sets of connections
unIP is the local IP address to bind to
pass in 0 if you just want the default local IP
unPort is the port to use
pass in 0 if you don't want users to be able to connect via IP/Port, but expect to be always peer-to-peer connections only

This is part of an older set of functions designed around the Berkeley TCP sockets model. It's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: SNetListenSocket_t

CreateP2PConnectionSocket

SNetSocket_t CreateP2PConnectionSocket( CSteamID steamIDTarget, int nVirtualPort, int nTimeoutSec, bool bAllowUseOfPacketRelay );
NameTypeDescription
steamIDTargetCSteamID
nVirtualPortint
nTimeoutSecint
bAllowUseOfPacketRelaybool

Creates a socket and begin connection to a remote destination.

can connect via a known Steam ID (client or game server), or directly to an IP
on success will trigger a SocketStatusCallback_t callback
on failure or timeout will trigger a SocketStatusCallback_t callback with a failure code in m_eSNetSocketState

This is part of an older set of functions designed around the Berkeley TCP sockets model it's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: SNetSocket_t

DestroyListenSocket

bool DestroyListenSocket( SNetListenSocket_t hSocket, bool bNotifyRemoteEnd );
NameTypeDescription
hSocketSNetListenSocket_t
bNotifyRemoteEndbool

Destroying a listen socket will automatically kill all the regular sockets generated from it.

This is part of an older set of functions designed around the Berkeley TCP sockets model. It's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: bool

DestroySocket

bool DestroySocket( SNetSocket_t hSocket, bool bNotifyRemoteEnd );
NameTypeDescription
hSocketSNetSocket_t
bNotifyRemoteEndbool

Disconnects the connection to the socket, if any, and invalidates the handle.

any unread data on the socket will be thrown away
if bNotifyRemoteEnd is set, socket will not be completely destroyed until the remote end acknowledges the disconnect

This is part of an older set of functions designed around the Berkeley TCP sockets model it's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: bool

GetListenSocketInfo

bool GetListenSocketInfo( SNetListenSocket_t hListenSocket, uint32 *pnIP, uint16 *pnPort );
NameTypeDescription
hListenSocketSNetListenSocket_t
pnIPuint32 *
pnPortuint16 *

Returns which local port the listen socket is bound to.

*pnIP and *pnPort will be 0 if the socket is set to listen for P2P connections only

This is part of an older set of functions designed around the Berkeley TCP sockets model. It's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: bool

GetMaxPacketSize

int GetMaxPacketSize( SNetSocket_t hSocket );
NameTypeDescription
hSocketSNetSocket_t

Gets the max packet size, in bytes.

This is part of an older set of functions designed around the Berkeley TCP sockets model it's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: int

GetP2PSessionState

bool GetP2PSessionState( CSteamID steamIDRemote, P2PSessionState_t *pConnectionState );
NameTypeDescription
steamIDRemoteCSteamIDThe user to get the active session state information of.
pConnectionStateP2PSessionState_t *Returns the state.

Fills out a P2PSessionState_t structure with details about the connection like whether or not there is an active connection; 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 needed for debugging purposes.

Returns: bool
true if pConnectionState was filled out; otherwise, false if there was no open session with the specified user.

Example:
P2PSessionState_t p2pSessionState; SteamNetworking()->GetP2PSessionState( steamIDremote, &p2pSessionState );

GetSocketConnectionType

ESNetSocketConnectionType GetSocketConnectionType( SNetSocket_t hSocket );
NameTypeDescription
hSocketSNetSocket_t

Returns true to describe how the socket ended up connecting.

This is part of an older set of functions designed around the Berkeley TCP sockets model. It's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: ESNetSocketConnectionType

GetSocketInfo

bool GetSocketInfo( SNetSocket_t hSocket, CSteamID *pSteamIDRemote, int *peSocketStatus, uint32 *punIPRemote, uint16 *punPortRemote );
NameTypeDescription
hSocketSNetSocket_t
pSteamIDRemoteCSteamID *
peSocketStatusint *
punIPRemoteuint32 *
punPortRemoteuint16 *

Returns information about the specified socket, filling out the contents of the pointers.

This is part of an older set of functions designed around the Berkeley TCP sockets model it's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: bool

IsDataAvailable

bool IsDataAvailable( SNetListenSocket_t hListenSocket, uint32 *pcubMsgSize, SNetSocket_t *phSocket );
NameTypeDescription
hListenSocketSNetListenSocket_t
pcubMsgSizeuint32 *
phSocketSNetSocket_t *

Checks for data from any socket that has been connected off this listen socket.

returns false if there is no data remaining
fills out *pcubMsgSize with the size of the next message, in bytes
fills out *phSocket with the socket that data is available on

This is part of an older set of functions designed around the Berkeley TCP sockets model. It's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: bool

IsDataAvailableOnSocket

bool IsDataAvailableOnSocket( SNetSocket_t hSocket, uint32 *pcubMsgSize );
NameTypeDescription
hSocketSNetSocket_t
pcubMsgSizeuint32 *

Returns false if there is no data remaining.

fills out *pcubMsgSize with the size of the next message, in bytes

This is part of an older set of functions designed around the Berkeley TCP sockets model it's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: bool

IsP2PPacketAvailable

bool IsP2PPacketAvailable( uint32 *pcubMsgSize, int nChannel = 0 );
NameTypeDescription
pcubMsgSizeuint32 *Returns the size of the packet.
nChannelintThe channel to check if a packet is available in.

Checks if a P2P packet is available to read, and gets the size of the message if there is one.

This should be called in a loop for each channel that you use. If there is a packet available you should call ReadP2PPacket to get the packet data.

Returns: bool
true if there is a packet available; otherwise, false.

ReadP2PPacket

bool ReadP2PPacket( void *pubDest, uint32 cubDest, uint32 *pcubMsgSize, CSteamID *psteamIDRemote, int nChannel = 0 );
NameTypeDescription
pubDestvoid *Returns the packet data by copying it into this buffer.
cubDestuint32The size allocated for pubDest. This should be either the same size returned by IsP2PPacketAvailable, or the size of your largest packet.
pcubMsgSizeuint32 *Returns the size of the packet.
psteamIDRemoteCSteamID *Returns the Steam ID of the user that sent this packet.
nChannelintThe channel the packet was sent over.

Reads in a packet that has been sent from another user via SendP2PPacket.


If the cubDest buffer is too small for the packet, then the message will be truncated.

This call is not blocking, and will return false if no data is available.

Before calling this you should have called IsP2PPacketAvailable.

Returns: bool
true if a packet was successfully read; otherwise, false if no packet was available.

Example:
uint32 msgSize = 0; while ( SteamNetworking()->IsP2PPacketAvailable( &msgSize ) ) { void *packet = malloc( msgSize ); CSteamID steamIDRemote; uint32 bytesRead = 0; if ( SteamNetworking()->ReadP2PPacket( packet, msgSize, &bytesRead, &steamIDRemote ) ) { // message dispatch code goes here } free( packet ); }

RetrieveData

bool RetrieveData( SNetListenSocket_t hListenSocket, void *pubDest, uint32 cubDest, uint32 *pcubMsgSize, SNetSocket_t *phSocket );
NameTypeDescription
hListenSocketSNetListenSocket_t
pubDestvoid *
cubDestuint32
pcubMsgSizeuint32 *
phSocketSNetSocket_t *

Retrieves data from any socket that has been connected off this listen socket.

fills in pubDest with the contents of the message
messages are always complete, of the same size as was sent (i.e. packetized, not streaming)
if *pcubMsgSize < cubDest, only partial data is written
returns false if no data is available
fills out *phSocket with the socket that data is available on

This is part of an older set of functions designed around the Berkeley TCP sockets model. It's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: bool

RetrieveDataFromSocket

bool RetrieveDataFromSocket( SNetSocket_t hSocket, void *pubDest, uint32 cubDest, uint32 *pcubMsgSize );
NameTypeDescription
hSocketSNetSocket_t
pubDestvoid *
cubDestuint32
pcubMsgSizeuint32 *

Fills in pubDest with the contents of the message.

messages are always complete, of the same size as was sent (i.e. packetized, not streaming)
if *pcubMsgSize < cubDest, only partial data is written
returns false if no data is available

This is part of an older set of functions designed around the Berkeley TCP sockets model it's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

Returns: bool

SendDataOnSocket

bool SendDataOnSocket( SNetSocket_t hSocket, void *pubData, uint32 cubData, bool bReliable );
NameTypeDescription
hSocketSNetSocket_t
pubDatavoid *
cubDatauint32
bReliablebool

sending data
must be a handle to a connected socket
data is all sent via UDP, and thus send sizes are limited to 1200 bytes; after this, many routers will start dropping packets
use the reliable flag with caution; although the resend rate is pretty aggressive,
it can still cause stalls in receiving data (like TCP)

Returns: bool

SendP2PPacket

bool SendP2PPacket( CSteamID steamIDRemote, const void *pubData, uint32 cubData, EP2PSend eP2PSendType, int nChannel = 0 );
NameTypeDescription
steamIDRemoteCSteamIDThe target user to send the packet to.
pubDataconst void *The raw byte array for the packet data to send. The maximum size of this packet is defined by eP2PSendType.
cubDatauint32The size in bytes of pubData.
eP2PSendTypeEP2PSendSpecifies how you want the data to be transmitted, such as reliably, unreliable, buffered, etc.
nChannelintThe channel which acts as a virtual port to send this packet on and allows you help route message to different systems.
You'll have to call ReadP2PPacket on the other end with the same channel number in order to retrieve the data on the other end. Using different channels to talk to the same user will still use the same underlying P2P connection, saving on resources.
Use 0 for the primary channel, or if you do not use this feature.

Sends a P2P packet to the specified user.

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

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

See EP2PSend 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.

Returns: bool
Triggers a P2PSessionRequest_t callback.
true if the packet was successfully sent.
Note that this does not mean successfully received, if we can't get through to the user after a timeout of 20 seconds, then an error will be posted via the P2PSessionConnectFail_t callback.

false upon the following conditions:
  • The packet is too large for the send type.
  • The target Steam ID is not valid.
  • There are too many bytes queued up to be sent.

Callbacks

These are callbacks which can be fired by calling SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ISteamNetworking.

P2PSessionConnectFail_t

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).

NameTypeDescription
m_steamIDRemoteCSteamIDUser we were trying to send the packets to.
m_eP2PSessionErroruint8Indicates the reason why we're having trouble. Actually a EP2PSessionError.

P2PSessionRequest_t

A user wants to communicate with us over the P2P channel via the SendP2PPacket. In response, a call to AcceptP2PSessionWithUser needs to be made, if you want to open the network channel with them.

NameTypeDescription
m_steamIDRemoteCSteamIDThe user who wants to start a P2P session with us.

Associated Functions: SendP2PPacket

SocketStatusCallback_t

Called when the status of a socket has changed, used as part of the CreateListenSocket and CreateP2PConnectionSocket calls.

This is part of an older set of functions designed around the Berkeley TCP sockets model. It's preferential that you use the P2P functions, they're more robust and these older functions will be removed eventually.

NameTypeDescription
m_hSocketSNetSocket_tthe socket used to send/receive data to the remote host
m_hListenSocketSNetListenSocket_tthis is the server socket that we were listening on; NULL if this was an outgoing connection
m_steamIDRemoteCSteamIDremote Steam ID we have connected to, if it has one
m_eSNetSocketStateintsocket state, ESNetSocketState

Structs

These are structs which functions in ISteamNetworking may return and/or interact with.

P2PSessionState_t

Connection state to a specified user, returned by GetP2PSessionState. 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.

NameTypeDescription
m_bConnectionActiveuint8Do we have an active open connection with the user (true) or not (false)?
m_bConnectinguint8Are we currently trying to establish a connection with the user (true) or not (false)?
m_eP2PSessionErroruint8Last error recorded on the socket. This returns a EP2PSessionError.
m_bUsingRelayuint8Is this connection going through a Steam relay server (true) or not (false)?
m_nBytesQueuedForSendint32The number of bytes queued up to be sent to the user.
m_nPacketsQueuedForSendint32The number of packets queued up to be sent to the user.
m_nRemoteIPuint32The IP of remote host if set. Could be a Steam relay server. This only exists for compatibility with older authentication api's.
m_nRemotePortuint16The Port of remote host if set. Could be a Steam relay server. This only exists for compatibility with older authentication api's.

Enums

These are enums which are defined for use with ISteamNetworking.

EP2PSend

Specifies the send type of SendP2PPacket.
Typically k_EP2PSendUnreliable is what you want for UDP-like packets, k_EP2PSendReliable for TCP-like packets

NameValueDescription
k_EP2PSendUnreliable0Basic 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.
k_EP2PSendUnreliableNoDelay1As above, 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, i.e. voice payload packets
k_EP2PSendReliable2Reliable 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.
k_EP2PSendReliableWithBuffering3As above, 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 k_EP2PSendReliableWithBuffering and then do a normal k_EP2PSendReliable to force all the buffered data to be sent.

EP2PSessionError

List of possible errors returned by SendP2PPacket, these will be sent in the P2PSessionConnectFail_t callback.

NameValueDescription
k_EP2PSessionErrorNone0There was no error.
k_EP2PSessionErrorNotRunningApp1The target user is not running the same game.
k_EP2PSessionErrorNoRightsToApp2The local user doesn't own the app that is running.
k_EP2PSessionErrorDestinationNotLoggedIn3Target user isn't connected to Steam.
k_EP2PSessionErrorTimeout4The connection timed out because the target user didn't respond, perhaps they aren't calling AcceptP2PSessionWithUser.
Corporate firewalls can also block this (NAT traversal is not firewall traversal), make sure that UDP ports 3478, 4379, and 4380 are open in an outbound direction.
k_EP2PSessionErrorMax5Unused.

ESNetSocketConnectionType

Describes how the socket is currently connected. Only used by the old networking API.

NameValueDescription
k_ESNetSocketConnectionTypeNotConnected0
k_ESNetSocketConnectionTypeUDP1
k_ESNetSocketConnectionTypeUDPRelay2

ESNetSocketState

Connection progress indicators, used by CreateP2PConnectionSocket.

NameValueDescription
k_ESNetSocketStateInvalid0
k_ESNetSocketStateConnected1communication is valid
k_ESNetSocketStateInitiated10states while establishing a connection
the connection state machine has started
k_ESNetSocketStateLocalCandidatesFound11p2p connections
we've found our local IP info
k_ESNetSocketStateReceivedRemoteCandidates12we've received information from the remote machine, via the Steam back-end, about their IP info
k_ESNetSocketStateChallengeHandshake15direct connections
we've received a challenge packet from the server
k_ESNetSocketStateDisconnecting21failure states
the API shut it down, and we're in the process of telling the other end
k_ESNetSocketStateLocalDisconnect22the API shut it down, and we've completed shutdown
k_ESNetSocketStateTimeoutDuringConnect23we timed out while trying to creating the connection
k_ESNetSocketStateRemoteEndDisconnected24the remote end has disconnected from us
k_ESNetSocketStateConnectionBroken25connection has been broken; either the other end has disappeared or our local network connection has broke

Typedefs

These are typedefs which are defined for use with ISteamNetworking.

NameBase typeDescription
SNetListenSocket_tuint32CreateListenSocket()
SNetSocket_tuint32handle to a socket
CreateP2PConnectionSocket()

Constants

These are constants which are defined for use with ISteamNetworking.

NameTypeValueDescription
STEAMNETWORKING_INTERFACE_VERSIONconst char *"SteamNetworking005"