diff options
Diffstat (limited to 'lib/linux/include/steam/isteamnetworkingmessages.h')
| -rw-r--r-- | lib/linux/include/steam/isteamnetworkingmessages.h | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/lib/linux/include/steam/isteamnetworkingmessages.h b/lib/linux/include/steam/isteamnetworkingmessages.h new file mode 100644 index 0000000..b7a2cd0 --- /dev/null +++ b/lib/linux/include/steam/isteamnetworkingmessages.h @@ -0,0 +1,198 @@ +//====== Copyright Valve Corporation, All rights reserved. ==================== + +#ifndef ISTEAMNETWORKINGMESSAGES +#define ISTEAMNETWORKINGMESSAGES +#pragma once + +#include "steamnetworkingtypes.h" +#include "steam_api_common.h" + +//----------------------------------------------------------------------------- +/// The non-connection-oriented interface to send and receive messages +/// (whether they be "clients" or "servers"). +/// +/// ISteamNetworkingSockets is connection-oriented (like TCP), meaning you +/// need to listen and connect, and then you send messages using a connection +/// handle. ISteamNetworkingMessages is more like UDP, in that you can just send +/// messages to arbitrary peers at any time. The underlying connections are +/// established implicitly. +/// +/// Under the hood ISteamNetworkingMessages works on top of the ISteamNetworkingSockets +/// code, so you get the same routing and messaging efficiency. The difference is +/// mainly in your responsibility to explicitly establish a connection and +/// the type of feedback you get about the state of the connection. Both +/// interfaces can do "P2P" communications, and both support both unreliable +/// and reliable messages, fragmentation and reassembly. +/// +/// The primary purpose of this interface is to be "like UDP", so that UDP-based code +/// can be ported easily to take advantage of relayed connections. If you find +/// yourself needing more low level information or control, or to be able to better +/// handle failure, then you probably need to use ISteamNetworkingSockets directly. +/// Also, note that if your main goal is to obtain a connection between two peers +/// without concerning yourself with assigning roles of "client" and "server", +/// you may find the symmetric connection mode of ISteamNetworkingSockets useful. +/// (See k_ESteamNetworkingConfig_SymmetricConnect.) +/// +class ISteamNetworkingMessages +{ +public: + /// Sends a message to the specified host. If we don't already have a session with that user, + /// a session is implicitly created. There might be some handshaking that needs to happen + /// before we can actually begin sending message data. If this handshaking fails and we can't + /// get through, an error will be posted via the callback SteamNetworkingMessagesSessionFailed_t. + /// There is no notification when the operation succeeds. (You should have the peer send a reply + /// for this purpose.) + /// + /// Sending a message to a host will also implicitly accept any incoming connection from that host. + /// + /// nSendFlags is a bitmask of k_nSteamNetworkingSend_xxx options + /// + /// nRemoteChannel is a routing number you can use to help route message to different systems. + /// You'll have to call ReceiveMessagesOnChannel() 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 + /// connection, saving on resources. If you don't need this feature, use 0. + /// Otherwise, small integers are the most efficient. + /// + /// It is guaranteed that reliable messages to the same host on the same channel + /// will be be received by the remote host (if they are received at all) exactly once, + /// and in the same order that they were sent. + /// + /// NO other order guarantees exist! In particular, unreliable messages may be dropped, + /// received out of order with respect to each other and with respect to reliable data, + /// or may be received multiple times. Messages on different channels are *not* guaranteed + /// to be received in the order they were sent. + /// + /// A note for those familiar with TCP/IP ports, or converting an existing codebase that + /// opened multiple sockets: You might notice that there is only one channel, and with + /// TCP/IP each endpoint has a port number. You can think of the channel number as the + /// *destination* port. If you need each message to also include a "source port" (so the + /// recipient can route the reply), then just put that in your message. That is essentially + /// how UDP works! + /// + /// Returns: + /// - k_EREsultOK on success. + /// - k_EResultNoConnection, if the session has failed or was closed by the peer and + /// k_nSteamNetworkingSend_AutoRestartBrokenSession was not specified. (You can + /// use GetSessionConnectionInfo to get the details.) In order to acknowledge the + /// broken session and start a new one, you must call CloseSessionWithUser, or you may + /// repeat the call with k_nSteamNetworkingSend_AutoRestartBrokenSession. See + /// k_nSteamNetworkingSend_AutoRestartBrokenSession for more details. + /// - See ISteamNetworkingSockets::SendMessageToConnection for more possible return values + virtual EResult SendMessageToUser( const SteamNetworkingIdentity &identityRemote, const void *pubData, uint32 cubData, int nSendFlags, int nRemoteChannel ) = 0; + + /// Reads the next message that has been sent from another user via SendMessageToUser() on the given channel. + /// Returns number of messages returned into your list. (0 if no message are available on that channel.) + /// + /// When you're done with the message object(s), make sure and call SteamNetworkingMessage_t::Release()! + virtual int ReceiveMessagesOnChannel( int nLocalChannel, SteamNetworkingMessage_t **ppOutMessages, int nMaxMessages ) = 0; + + /// Call this in response to a SteamNetworkingMessagesSessionRequest_t callback. + /// SteamNetworkingMessagesSessionRequest_t are posted when a user tries to send you a message, + /// and you haven't tried to talk to them first. If you don't want to talk to them, just ignore + /// the request. If the user continues to send you messages, SteamNetworkingMessagesSessionRequest_t + /// callbacks will continue to be posted periodically. + /// + /// Returns false if there is no session with the user pending or otherwise. If there is an + /// existing active session, this function will return true, even if it is not pending. + /// + /// Calling SendMessageToUser() will implicitly accepts any pending session request to that user. + virtual bool AcceptSessionWithUser( const SteamNetworkingIdentity &identityRemote ) = 0; + + /// Call this when you're done talking to a user to immediately free up resources under-the-hood. + /// If the remote user tries to send data to you again, another SteamNetworkingMessagesSessionRequest_t + /// callback will be posted. + /// + /// Note that sessions that go unused for a few minutes are automatically timed out. + virtual bool CloseSessionWithUser( const SteamNetworkingIdentity &identityRemote ) = 0; + + /// Call this when you're done talking to a user on a specific channel. Once all + /// open channels to a user have been closed, the open session to the user will be + /// closed, and any new data from this user will trigger a + /// SteamSteamNetworkingMessagesSessionRequest_t callback + virtual bool CloseChannelWithUser( const SteamNetworkingIdentity &identityRemote, int nLocalChannel ) = 0; + + /// Returns information about the latest state of a connection, if any, with the given peer. + /// Primarily intended for debugging purposes, but can also be used to get more detailed + /// failure information. (See SendMessageToUser and k_nSteamNetworkingSend_AutoRestartBrokenSession.) + /// + /// Returns the value of SteamNetConnectionInfo_t::m_eState, or k_ESteamNetworkingConnectionState_None + /// if no connection exists with specified peer. You may pass nullptr for either parameter if + /// you do not need the corresponding details. Note that sessions time out after a while, + /// so if a connection fails, or SendMessageToUser returns k_EResultNoConnection, you cannot wait + /// indefinitely to obtain the reason for failure. + virtual ESteamNetworkingConnectionState GetSessionConnectionInfo( const SteamNetworkingIdentity &identityRemote, SteamNetConnectionInfo_t *pConnectionInfo, SteamNetConnectionRealTimeStatus_t *pQuickStatus ) = 0; +}; +#define STEAMNETWORKINGMESSAGES_INTERFACE_VERSION "SteamNetworkingMessages002" + +// +// Callbacks +// + +#pragma pack( push, 1 ) + +/// Posted when a remote host is sending us a message, and we do not already have a session with them +struct SteamNetworkingMessagesSessionRequest_t +{ + enum { k_iCallback = k_iSteamNetworkingMessagesCallbacks + 1 }; + SteamNetworkingIdentity m_identityRemote; // user who wants to talk to us +}; + +/// Posted when we fail to establish a connection, or we detect that communications +/// have been disrupted it an unusual way. There is no notification when a peer proactively +/// closes the session. ("Closed by peer" is not a concept of UDP-style communications, and +/// SteamNetworkingMessages is primarily intended to make porting UDP code easy.) +/// +/// Remember: callbacks are asynchronous. See notes on SendMessageToUser, +/// and k_nSteamNetworkingSend_AutoRestartBrokenSession in particular. +/// +/// Also, if a session times out due to inactivity, no callbacks will be posted. The only +/// way to detect that this is happening is that querying the session state may return +/// none, connecting, and findingroute again. +struct SteamNetworkingMessagesSessionFailed_t +{ + enum { k_iCallback = k_iSteamNetworkingMessagesCallbacks + 2 }; + + /// Detailed info about the session that failed. + /// SteamNetConnectionInfo_t::m_identityRemote indicates who this session + /// was with. + SteamNetConnectionInfo_t m_info; +}; + +#pragma pack(pop) + +// Global accessors + +// Using standalone lib +#ifdef STEAMNETWORKINGSOCKETS_STANDALONELIB + + static_assert( STEAMNETWORKINGMESSAGES_INTERFACE_VERSION[25] == '2', "Version mismatch" ); + + STEAMNETWORKINGSOCKETS_INTERFACE ISteamNetworkingMessages *SteamNetworkingMessages_LibV2(); + inline ISteamNetworkingMessages *SteamNetworkingMessages_Lib() { return SteamNetworkingMessages_LibV2(); } + + // If running in context of steam, we also define a gameserver instance. + STEAMNETWORKINGSOCKETS_INTERFACE ISteamNetworkingMessages *SteamGameServerNetworkingMessages_LibV2(); + inline ISteamNetworkingMessages *SteamGameServerNetworkingMessages_Lib() { return SteamGameServerNetworkingMessages_LibV2(); } + + #ifndef STEAMNETWORKINGSOCKETS_STEAMAPI + inline ISteamNetworkingMessages *SteamNetworkingMessages() { return SteamNetworkingMessages_LibV2(); } + inline ISteamNetworkingMessages *SteamGameServerNetworkingMessages() { return SteamGameServerNetworkingMessages_LibV2(); } + #endif +#endif + +// Using Steamworks SDK +#ifdef STEAMNETWORKINGSOCKETS_STEAMAPI + + // Steamworks SDK + STEAM_DEFINE_USER_INTERFACE_ACCESSOR( ISteamNetworkingMessages *, SteamNetworkingMessages_SteamAPI, STEAMNETWORKINGMESSAGES_INTERFACE_VERSION ); + STEAM_DEFINE_GAMESERVER_INTERFACE_ACCESSOR( ISteamNetworkingMessages *, SteamGameServerNetworkingMessages_SteamAPI, STEAMNETWORKINGMESSAGES_INTERFACE_VERSION ); + + #ifndef STEAMNETWORKINGSOCKETS_STANDALONELIB + inline ISteamNetworkingMessages *SteamNetworkingMessages() { return SteamNetworkingMessages_SteamAPI(); } + inline ISteamNetworkingMessages *SteamGameServerNetworkingMessages() { return SteamGameServerNetworkingMessages_SteamAPI(); } + #endif +#endif + +#endif // ISTEAMNETWORKINGMESSAGES |