Netværksfunktioner til at lave forbindelser og sende data mellem klienter via NAT, når det er muligt.
NOTE: This API is deprecated and may be removed in a future Steamworks SDK release. Please use
ISteamNetworkingSockets or
ISteamNetworkingMessages instead. See the
Steam-netværk overview for more information.
Medlemsfunktioner
Member functions for
ISteamNetworking
are called through the global accessor function
SteamNetworking()
.
AcceptP2PSessionWithUser
bool AcceptP2PSessionWithUser( CSteamID steamIDRemote );
Navn | Type | Beskrivelse |
steamIDRemote | CSteamID | Steam-ID'et tilhørende brugeren, som sendte den første pakke til os. |
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!
Returværdier: bool
true, upon success;
false only if
steamIDRemote
is invalid.
AllowP2PPacketRelay
bool AllowP2PPacketRelay( bool bAllow );
Navn | Type | Beskrivelse |
bAllow | bool | |
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.
Returværdier: bool
This function always returns
true.
CloseP2PChannelWithUser
bool CloseP2PChannelWithUser( CSteamID steamIDRemote, int nChannel );
Navn | Type | Beskrivelse |
steamIDRemote | CSteamID | Steam-ID'et til brugeren, hvis forbindelse du vil lukke. |
nChannel | int | Kanalen, der skal lukkes. |
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.
Returværdier: 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 );
Navn | Type | Beskrivelse |
steamIDRemote | CSteamID | Steam-ID'et til brugeren, hvis forbindelse du vil lukke. |
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.
Returværdier: 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 );
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.
Returværdier: SNetSocket_tCreateListenSocket
SNetListenSocket_t CreateListenSocket( int nVirtualP2PPort, uint32 nIP, uint16 nPort, bool bAllowUseOfPacketRelay );
Navn | Type | Beskrivelse |
nVirtualP2PPort | int | |
nIP | uint32 | |
nPort | uint16 | |
bAllowUseOfPacketRelay | bool | |
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.
Returværdier: SNetListenSocket_tCreateP2PConnectionSocket
SNetSocket_t CreateP2PConnectionSocket( CSteamID steamIDTarget, int nVirtualPort, int nTimeoutSec, bool bAllowUseOfPacketRelay );
Navn | Type | Beskrivelse |
steamIDTarget | CSteamID | |
nVirtualPort | int | |
nTimeoutSec | int | |
bAllowUseOfPacketRelay | bool | |
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.
Returværdier: SNetSocket_tDestroyListenSocket
bool DestroyListenSocket( SNetListenSocket_t hSocket, bool bNotifyRemoteEnd );
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.
Returværdier: bool
DestroySocket
bool DestroySocket( SNetSocket_t hSocket, bool bNotifyRemoteEnd );
Navn | Type | Beskrivelse |
hSocket | SNetSocket_t | |
bNotifyRemoteEnd | bool | |
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.
Returværdier: bool
GetListenSocketInfo
bool GetListenSocketInfo( SNetListenSocket_t hListenSocket, uint32 *pnIP, uint16 *pnPort );
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.
Returværdier: bool
GetMaxPacketSize
int GetMaxPacketSize( SNetSocket_t hSocket );
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.
Returværdier: int
GetP2PSessionState
bool GetP2PSessionState( CSteamID steamIDRemote, P2PSessionState_t *pConnectionState );
Navn | Type | Beskrivelse |
steamIDRemote | CSteamID | Brugeren, som der skal hentes tilstandsoplysninger om den aktive session fra. |
pConnectionState | P2PSessionState_t * | Returnerer tilstanden. |
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.
Returværdier: bool
true, if
pConnectionState
was filled out; otherwise,
false if there was no open session with the specified user.
Eksempel:P2PSessionState_t p2pSessionState;
SteamNetworking()->GetP2PSessionState( steamIDremote, &p2pSessionState );
GetSocketConnectionType
ESNetSocketConnectionType GetSocketConnectionType( SNetSocket_t hSocket );
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.
Returværdier: ESNetSocketConnectionTypeGetSocketInfo
bool GetSocketInfo( SNetSocket_t hSocket, CSteamID *pSteamIDRemote, int *peSocketStatus, uint32 *punIPRemote, uint16 *punPortRemote );
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.
Returværdier: bool
IsDataAvailable
bool IsDataAvailable( SNetListenSocket_t hListenSocket, uint32 *pcubMsgSize, SNetSocket_t *phSocket );
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.
Returværdier: bool
IsDataAvailableOnSocket
bool IsDataAvailableOnSocket( SNetSocket_t hSocket, uint32 *pcubMsgSize );
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.
Returværdier: bool
IsP2PPacketAvailable
bool IsP2PPacketAvailable( uint32 *pcubMsgSize, int nChannel = 0 );
Navn | Type | Beskrivelse |
pcubMsgSize | uint32 * | Returnerer størrelsen på pakken. |
nChannel | int | Kanalen, hvor det skal tjekkes, om der er en pakke. |
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.
Returværdier: bool
true, if there is a packet available; otherwise,
false.
ReadP2PPacket
bool ReadP2PPacket( void *pubDest, uint32 cubDest, uint32 *pcubMsgSize, CSteamID *psteamIDRemote, int nChannel = 0 );
Navn | Type | Beskrivelse |
pubDest | void * | Returnerer pakkedataene ved at kopiere dem over i denne buffer. |
cubDest | uint32 | Den allokerede størrelse for pubDest . Dette skal være enten samme størrelse som den, der returneres af IsP2PPacketAvailable, eller størrelsen på den største pakke. |
pcubMsgSize | uint32 * | Returnerer størrelsen på pakken. |
psteamIDRemote | CSteamID * | Returnerer Steam-ID'et på brugeren, som sendte denne pakke. |
nChannel | int | Kanalen, som pakken blev sendt via. |
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.
Returværdier: bool
true, if a packet was successfully read; otherwise,
false if no packet was available.
Eksempel:uint32 msgSize = 0;
while ( SteamNetworking()->IsP2PPacketAvailable( &msgSize ) )
{
void *packet = malloc( msgSize );
CSteamID steamIDRemote;
uint32 bytesRead = 0;
if ( SteamNetworking()->ReadP2PPacket( packet, msgSize, &bytesRead, &steamIDRemote ) )
{
// afsendelseskoden for meddelelsen står her
}
free( packet );
}
RetrieveData
bool RetrieveData( SNetListenSocket_t hListenSocket, void *pubDest, uint32 cubDest, uint32 *pcubMsgSize, SNetSocket_t *phSocket );
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.
Returværdier: bool
RetrieveDataFromSocket
bool RetrieveDataFromSocket( SNetSocket_t hSocket, void *pubDest, uint32 cubDest, uint32 *pcubMsgSize );
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.
Returværdier: bool
SendDataOnSocket
bool SendDataOnSocket( SNetSocket_t hSocket, void *pubData, uint32 cubData, bool bReliable );
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)
Returværdier: bool
SendP2PPacket
bool SendP2PPacket( CSteamID steamIDRemote, const void *pubData, uint32 cubData, EP2PSend eP2PSendType, int nChannel = 0 );
Navn | Type | Beskrivelse |
steamIDRemote | CSteamID | Målbrugeren, som pakken skal sendes til. |
pubData | const void * | Det rå byte array af pakken, som skal sendes. Den maksimale størrelse på pakken defineres af eP2PSendType . |
cubData | uint32 | Størrelsen af pubData i bytes. |
eP2PSendType | EP2PSend | Angiver, hvordan du vil have, at dataene skal sendes, f.eks. pålideligt, upålideligt, med buffer osv. |
nChannel | int | Kanalen, som fungerer som en virtuel port, som pakken skal sendes på, og som gør det muligt for dig at sende meddelelser til forskellige systemer. Du skal kalde ReadP2PPacket i den anden ende med det samme kanalnummer for at hente data i den anden ende. Brug af forskellige kanaler til at tale med den samme bruger vil stadig bruge den samme underliggende P2P-forbindelse og spare ressourcer. Brug 0 for den primære kanal, eller hvis du ikke bruger denne funktion. |
Sends a P2P packet to the specified user.
This is a session-less API which automatically establishes NAT-traversing or Steam relay server connections.
BEMÆRK: 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.
Returværdier: 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:
- Pakken er for stor til afsendelsestypen.
- Destinations-Steam-ID'et er ikke gyldigt.
- Der er for mange bytes i kø, der skal sendes.
Tilbagekald
Disse er tilbagekald, som kan aktiveres ved at kalde
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).
Navn | Type | Beskrivelse |
m_steamIDRemote | CSteamID | Brugeren, som vi prøver at sende pakkerne til. |
m_eP2PSessionError | uint8 | Indikerer årsagen til, at vi har problemer. Faktisk 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.
Navn | Type | Beskrivelse |
m_steamIDRemote | CSteamID | Brugeren, som vil starte en P2P-session med os. |
Tilknyttede funktioner: SendP2PPacketSocketStatusCallback_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.
Navn | Type | Beskrivelse |
m_hSocket | SNetSocket_t | Den socket, der bruges til at sende/modtage data til fjernværten. |
m_hListenSocket | SNetListenSocket_t | Det er den server socket, som vi lyttede til. NULL, hvis dette var en udgående forbindelse. |
m_steamIDRemote | CSteamID | Fjern-Steam-ID, som vi har oprettet forbindelse til, hvis der er et. |
m_eSNetSocketState | int | Socket-tilstand, 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.
Navn | Type | Beskrivelse |
m_bConnectionActive | uint8 | Har vi en aktiv, åben forbindelse med brugeren (true) eller ej (false)? |
m_bConnecting | uint8 | Forsøger vi i øjeblikket at etablere en forbindelse med brugeren (true) eller ej (false)? |
m_eP2PSessionError | uint8 | Sidste fejlkode, der blev registreret på denne socket. Dette returnerer et EP2PSessionError. |
m_bUsingRelay | uint8 | Går denne forbindelse gennem en Steam-relay-server (true) eller ej (false)? |
m_nBytesQueuedForSend | int32 | Antallet af bytes i kø, som skal sendes til brugeren. |
m_nPacketsQueuedForSend | int32 | Antallet af pakker i kø, som skal sendes til brugeren. |
m_nRemoteIP | uint32 | IP-adressen på fjernværten, hvis den er angivet. Kan være en Steam-relay-server. Dette findes kun for kompatibilitet med ældre godkendelses-API'er. |
m_nRemotePort | uint16 | Porten for fjernværten, hvis den er angivet. Kan være en Steam-relay-server. Dette findes kun for kompatibilitet med ældre godkendelses-API'er. |
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
Navn | Værdi | Beskrivelse |
k_EP2PSendUnreliable | 0 | Grundlæggende UDP-afsendelse. Pakker må ikke være større end 1200 bytes (typisk MTU-størrelse). Kan mistes eller ankomme i forkert rækkefølge (sjældent). API'en, som står for afsendelsen, har visse oplysninger om den underliggende forbindelse, så hvis NAT-traversal ikke lykkes, eller der sker en anerkendt justering på forbindelsen, batches pakken, indtil forbindelsen er åben igen. |
k_EP2PSendUnreliableNoDelay | 1 | Samme som ovenfor, men hvis den underliggende P2P-forbindelse ikke er etableret endnu, smides pakken bare væk. Hvis dette bruges på den første pakke, som sendes til en fjernvært, er det næsten garanteret, at pakken mistes. Dette er sådan set kun nyttigt, hvis du har data, som ikke kan bufferlagres, f.eks. taledatapakker. |
k_EP2PSendReliable | 2 | Afsendelse af pålidelig meddelelse. Kan sende op til 1 MB data i en enkelt meddelelse. Foretager fragmentering/samler meddelelser igen under motorhjelmen, og et glidende vindue bruges til effektivt at sende store datasegmenter. |
k_EP2PSendReliableWithBuffering | 3 | Samme som ovenfor, men når der sendes, anvendes Nagle-algoritmen. Afsendelsesdata indsamles til den aktuelle MTU-størrelse (typisk ca. 1200 bytes, men værdien kan ændre sig) eller efter ca. 200 ms (Nagle-algoritmen). Dette er nyttigt, når du vil sende et sæt mindre meddelelser men kombinere dem i én pakke. Da den pålidelige stream er bestilt, kan du foretage flere små afsendelser af meddelelser med k_EP2PSendReliableWithBuffering og derefter foretage en almindelig k_EP2PSendReliable for at tvinge afsendelse af alle data i bufferen. |
EP2PSessionError
List of possible errors returned by
SendP2PPacket, these will be sent in the
P2PSessionConnectFail_t callback.
Navn | Værdi | Beskrivelse |
k_EP2PSessionErrorNone | 0 | Der opstod en fejl. |
k_EP2PSessionErrorNotRunningApp | 1 | Målbrugeren kører ikke det samme spil. |
k_EP2PSessionErrorNoRightsToApp | 2 | Den lokale bruger ejer ikke den app, der køres. |
k_EP2PSessionErrorDestinationNotLoggedIn | 3 | Målbrugeren har ikke forbindelse til Steam. |
k_EP2PSessionErrorTimeout | 4 | Der opstod timeout for forbindelsen, fordi målbrugeren ikke svarede. Måske kalder målbrugeren ikke AcceptP2PSessionWithUser. Firewalls hos virksomheder kan også blokere (NAT-traversal betyder ikke passage gennem en firewall). Sørg for, at UDP-port 3478, 4379 og 4380 er åben i udgående retning. |
k_EP2PSessionErrorMax | 5 | Ubrugt. |
ESNetSocketConnectionType
Describes how the socket is currently connected. Only used by the old networking API.
Navn | Værdi | Beskrivelse |
k_ESNetSocketConnectionTypeNotConnected | 0 | |
k_ESNetSocketConnectionTypeUDP | 1 | |
k_ESNetSocketConnectionTypeUDPRelay | 2 | |
ESNetSocketState
Connection progress indicators, used by
CreateP2PConnectionSocket.
Navn | Værdi | Beskrivelse |
k_ESNetSocketStateInvalid | 0 | |
k_ESNetSocketStateConnected | 1 | Kommunikation er gyldig. |
k_ESNetSocketStateInitiated | 10 | Tilstande under etablering af forbindelse. Forbindelsestilstandsmaskinen kører. |
k_ESNetSocketStateLocalCandidatesFound | 11 | P2P-forbindelser. Vi har fundet vores lokale IP-oplysninger. |
k_ESNetSocketStateReceivedRemoteCandidates | 12 | Vi har modtaget IP-oplysninger fra fjernmaskinen, via Steams backend. |
k_ESNetSocketStateChallengeHandshake | 15 | Direkte forbindelser. Vi har modtaget en challenge-pakke fra serveren. |
k_ESNetSocketStateDisconnecting | 21 | Fejltilstande. API'en lukkede den ned, og vi var i gang med at give den anden ende besked. |
k_ESNetSocketStateLocalDisconnect | 22 | API'en lukkede den ned, og vi har gennemført nedlukningen. |
k_ESNetSocketStateTimeoutDuringConnect | 23 | Vi fik timeout, mens vi forsøgte at oprette forbindelse. |
k_ESNetSocketStateRemoteEndDisconnected | 24 | Fjernenden har afbrudt forbindelsen til os. |
k_ESNetSocketStateConnectionBroken | 25 | Forbindelsen blev afbrudt. Enten forsvandt den anden ende, eller vores lokale netværksforbindelse blev afbrudt. |
Typedefs
These are typedefs which are defined for use with ISteamNetworking.
Navn | Basistype | Beskrivelse |
SNetListenSocket_t | uint32 | CreateListenSocket() |
SNetSocket_t | uint32 | Handle til en socket. CreateP2PConnectionSocket() |
Konstanter
These are constants which are defined for use with ISteamNetworking.
Navn | Type | Værdi | Beskrivelse |
STEAMNETWORKING_INTERFACE_VERSION | const char * | "SteamNetworking005" | |