public/steam/isteamgameserver.h
author Nicholas Hastings <nshastings@gmail.com>
Sun Nov 03 09:37:43 2013 -0500 (2013-11-03)
changeset 29 e827f56d0c8f
permissions -rw-r--r--
Recompile linux and mac tier1.
     1 //========= Copyright Valve Corporation, All rights reserved. ============//
     2 //
     3 // Purpose: interface to steam for game servers
     4 //
     5 //=============================================================================
     6 
     7 #ifndef ISTEAMGAMESERVER_H
     8 #define ISTEAMGAMESERVER_H
     9 #ifdef _WIN32
    10 #pragma once
    11 #endif
    12 
    13 #include "isteamclient.h"
    14 
    15 #define MASTERSERVERUPDATERPORT_USEGAMESOCKETSHARE	((uint16)-1)
    16 
    17 //-----------------------------------------------------------------------------
    18 // Purpose: Functions for authenticating users via Steam to play on a game server
    19 //-----------------------------------------------------------------------------
    20 class ISteamGameServer
    21 {
    22 public:
    23 
    24 //
    25 // Basic server data.  These properties, if set, must be set before before calling LogOn.  They
    26 // may not be changed after logged in.
    27 //
    28 
    29 	/// This is called by SteamGameServer_Init, and you will usually not need to call it directly
    30 	virtual bool InitGameServer( uint32 unIP, uint16 usGamePort, uint16 usQueryPort, uint32 unFlags, AppId_t nGameAppId, const char *pchVersionString ) = 0;
    31 
    32 	/// Game product identifier.  This is currently used by the master server for version checking purposes.
    33 	/// It's a required field, but will eventually will go away, and the AppID will be used for this purpose.
    34 	virtual void SetProduct( const char *pszProduct ) = 0;
    35 
    36 	/// Description of the game.  This is a required field and is displayed in the steam server browser....for now.
    37 	/// This is a required field, but it will go away eventually, as the data should be determined from the AppID.
    38 	virtual void SetGameDescription( const char *pszGameDescription ) = 0;
    39 
    40 	/// If your game is a "mod," pass the string that identifies it.  The default is an empty string, meaning
    41 	/// this application is the original game, not a mod.
    42 	///
    43 	/// @see k_cbMaxGameServerGameDir
    44 	virtual void SetModDir( const char *pszModDir ) = 0;
    45 
    46 	/// Is this is a dedicated server?  The default value is false.
    47 	virtual void SetDedicatedServer( bool bDedicated ) = 0;
    48 
    49 //
    50 // Login
    51 //
    52 
    53 	/// Begin process to login to a persistent game server account
    54 	///
    55 	/// You need to register for callbacks to determine the result of this operation.
    56 	/// @see SteamServersConnected_t
    57 	/// @see SteamServerConnectFailure_t
    58 	/// @see SteamServersDisconnected_t
    59 	virtual void LogOn(
    60 		const char *pszAccountName,
    61 		const char *pszPassword
    62 	) = 0;
    63 
    64 	/// Login to a generic, anonymous account.
    65 	///
    66 	/// Note: in previous versions of the SDK, this was automatically called within SteamGameServer_Init,
    67 	/// but this is no longer the case.
    68 	virtual void LogOnAnonymous() = 0;
    69 
    70 	/// Begin process of logging game server out of steam
    71 	virtual void LogOff() = 0;
    72 	
    73 	// status functions
    74 	virtual bool BLoggedOn() = 0;
    75 	virtual bool BSecure() = 0; 
    76 	virtual CSteamID GetSteamID() = 0;
    77 
    78 	/// Returns true if the master server has requested a restart.
    79 	/// Only returns true once per request.
    80 	virtual bool WasRestartRequested() = 0;
    81 
    82 //
    83 // Server state.  These properties may be changed at any time.
    84 //
    85 
    86 	/// Max player count that will be reported to server browser and client queries
    87 	virtual void SetMaxPlayerCount( int cPlayersMax ) = 0;
    88 
    89 	/// Number of bots.  Default value is zero
    90 	virtual void SetBotPlayerCount( int cBotplayers ) = 0;
    91 
    92 	/// Set the name of server as it will appear in the server browser
    93 	///
    94 	/// @see k_cbMaxGameServerName
    95 	virtual void SetServerName( const char *pszServerName ) = 0;
    96 
    97 	/// Set name of map to report in the server browser
    98 	///
    99 	/// @see k_cbMaxGameServerName
   100 	virtual void SetMapName( const char *pszMapName ) = 0;
   101 
   102 	/// Let people know if your server will require a password
   103 	virtual void SetPasswordProtected( bool bPasswordProtected ) = 0;
   104 
   105 	/// Spectator server.  The default value is zero, meaning the service
   106 	/// is not used.
   107 	virtual void SetSpectatorPort( uint16 unSpectatorPort ) = 0;
   108 
   109 	/// Name of the spectator server.  (Only used if spectator port is nonzero.)
   110 	///
   111 	/// @see k_cbMaxGameServerMapName
   112 	virtual void SetSpectatorServerName( const char *pszSpectatorServerName ) = 0;
   113 
   114 	/// Call this to clear the whole list of key/values that are sent in rules queries.
   115 	virtual void ClearAllKeyValues() = 0;
   116 	
   117 	/// Call this to add/update a key/value pair.
   118 	virtual void SetKeyValue( const char *pKey, const char *pValue ) = 0;
   119 
   120 	/// Sets a string defining the "gametags" for this server, this is optional, but if it is set
   121 	/// it allows users to filter in the matchmaking/server-browser interfaces based on the value
   122 	///
   123 	/// @see k_cbMaxGameServerTags
   124 	virtual void SetGameTags( const char *pchGameTags ) = 0; 
   125 
   126 	/// Sets a string defining the "gamedata" for this server, this is optional, but if it is set
   127 	/// it allows users to filter in the matchmaking/server-browser interfaces based on the value
   128 	/// don't set this unless it actually changes, its only uploaded to the master once (when
   129 	/// acknowledged)
   130 	///
   131 	/// @see k_cbMaxGameServerGameData
   132 	virtual void SetGameData( const char *pchGameData) = 0; 
   133 
   134 	/// Region identifier.  This is an optional field, the default value is empty, meaning the "world" region
   135 	virtual void SetRegion( const char *pszRegion ) = 0;
   136 
   137 //
   138 // Player list management / authentication
   139 //
   140 
   141 	// Handles receiving a new connection from a Steam user.  This call will ask the Steam
   142 	// servers to validate the users identity, app ownership, and VAC status.  If the Steam servers 
   143 	// are off-line, then it will validate the cached ticket itself which will validate app ownership 
   144 	// and identity.  The AuthBlob here should be acquired on the game client using SteamUser()->InitiateGameConnection()
   145 	// and must then be sent up to the game server for authentication.
   146 	//
   147 	// Return Value: returns true if the users ticket passes basic checks. pSteamIDUser will contain the Steam ID of this user. pSteamIDUser must NOT be NULL
   148 	// If the call succeeds then you should expect a GSClientApprove_t or GSClientDeny_t callback which will tell you whether authentication
   149 	// for the user has succeeded or failed (the steamid in the callback will match the one returned by this call)
   150 	virtual bool SendUserConnectAndAuthenticate( uint32 unIPClient, const void *pvAuthBlob, uint32 cubAuthBlobSize, CSteamID *pSteamIDUser ) = 0;
   151 
   152 	// Creates a fake user (ie, a bot) which will be listed as playing on the server, but skips validation.  
   153 	// 
   154 	// Return Value: Returns a SteamID for the user to be tracked with, you should call HandleUserDisconnect()
   155 	// when this user leaves the server just like you would for a real user.
   156 	virtual CSteamID CreateUnauthenticatedUserConnection() = 0;
   157 
   158 	// Should be called whenever a user leaves our game server, this lets Steam internally
   159 	// track which users are currently on which servers for the purposes of preventing a single
   160 	// account being logged into multiple servers, showing who is currently on a server, etc.
   161 	virtual void SendUserDisconnect( CSteamID steamIDUser ) = 0;
   162 
   163 	// Update the data to be displayed in the server browser and matchmaking interfaces for a user
   164 	// currently connected to the server.  For regular users you must call this after you receive a
   165 	// GSUserValidationSuccess callback.
   166 	// 
   167 	// Return Value: true if successful, false if failure (ie, steamIDUser wasn't for an active player)
   168 	virtual bool BUpdateUserData( CSteamID steamIDUser, const char *pchPlayerName, uint32 uScore ) = 0;
   169 
   170 	// New auth system APIs - do not mix with the old auth system APIs.
   171 	// ----------------------------------------------------------------
   172 
   173 	// Retrieve ticket to be sent to the entity who wishes to authenticate you ( using BeginAuthSession API ). 
   174 	// pcbTicket retrieves the length of the actual ticket.
   175 	virtual HAuthTicket GetAuthSessionTicket( void *pTicket, int cbMaxTicket, uint32 *pcbTicket ) = 0;
   176 
   177 	// Authenticate ticket ( from GetAuthSessionTicket ) from entity steamID to be sure it is valid and isnt reused
   178 	// Registers for callbacks if the entity goes offline or cancels the ticket ( see ValidateAuthTicketResponse_t callback and EAuthSessionResponse )
   179 	virtual EBeginAuthSessionResult BeginAuthSession( const void *pAuthTicket, int cbAuthTicket, CSteamID steamID ) = 0;
   180 
   181 	// Stop tracking started by BeginAuthSession - called when no longer playing game with this entity
   182 	virtual void EndAuthSession( CSteamID steamID ) = 0;
   183 
   184 	// Cancel auth ticket from GetAuthSessionTicket, called when no longer playing game with the entity you gave the ticket to
   185 	virtual void CancelAuthTicket( HAuthTicket hAuthTicket ) = 0;
   186 
   187 	// After receiving a user's authentication data, and passing it to SendUserConnectAndAuthenticate, use this function
   188 	// to determine if the user owns downloadable content specified by the provided AppID.
   189 	virtual EUserHasLicenseForAppResult UserHasLicenseForApp( CSteamID steamID, AppId_t appID ) = 0;
   190 
   191 	// Ask if a user in in the specified group, results returns async by GSUserGroupStatus_t
   192 	// returns false if we're not connected to the steam servers and thus cannot ask
   193 	virtual bool RequestUserGroupStatus( CSteamID steamIDUser, CSteamID steamIDGroup ) = 0;
   194 
   195 //
   196 // Query steam for server data
   197 //
   198 
   199 	// Ask for the gameplay stats for the server. Results returned in a callback
   200 	virtual void GetGameplayStats( ) = 0;
   201 
   202 	// Gets the reputation score for the game server. This API also checks if the server or some
   203 	// other server on the same IP is banned from the Steam master servers.
   204 	virtual SteamAPICall_t GetServerReputation( ) = 0;
   205 
   206 	// Returns the public IP of the server according to Steam, useful when the server is 
   207 	// behind NAT and you want to advertise its IP in a lobby for other clients to directly
   208 	// connect to
   209 	virtual uint32 GetPublicIP() = 0;
   210 
   211 // These are in GameSocketShare mode, where instead of ISteamGameServer creating its own
   212 // socket to talk to the master server on, it lets the game use its socket to forward messages
   213 // back and forth. This prevents us from requiring server ops to open up yet another port
   214 // in their firewalls.
   215 //
   216 // the IP address and port should be in host order, i.e 127.0.0.1 == 0x7f000001
   217 	
   218 	// These are used when you've elected to multiplex the game server's UDP socket
   219 	// rather than having the master server updater use its own sockets.
   220 	// 
   221 	// Source games use this to simplify the job of the server admins, so they 
   222 	// don't have to open up more ports on their firewalls.
   223 	
   224 	// Call this when a packet that starts with 0xFFFFFFFF comes in. That means
   225 	// it's for us.
   226 	virtual bool HandleIncomingPacket( const void *pData, int cbData, uint32 srcIP, uint16 srcPort ) = 0;
   227 
   228 	// AFTER calling HandleIncomingPacket for any packets that came in that frame, call this.
   229 	// This gets a packet that the master server updater needs to send out on UDP.
   230 	// It returns the length of the packet it wants to send, or 0 if there are no more packets to send.
   231 	// Call this each frame until it returns 0.
   232 	virtual int GetNextOutgoingPacket( void *pOut, int cbMaxOut, uint32 *pNetAdr, uint16 *pPort ) = 0;
   233 
   234 //
   235 // Control heartbeats / advertisement with master server
   236 //
   237 
   238 	// Call this as often as you like to tell the master server updater whether or not
   239 	// you want it to be active (default: off).
   240 	virtual void EnableHeartbeats( bool bActive ) = 0;
   241 
   242 	// You usually don't need to modify this.
   243 	// Pass -1 to use the default value for iHeartbeatInterval.
   244 	// Some mods change this.
   245 	virtual void SetHeartbeatInterval( int iHeartbeatInterval ) = 0;
   246 
   247 	// Force a heartbeat to steam at the next opportunity
   248 	virtual void ForceHeartbeat() = 0;
   249 
   250 	// associate this game server with this clan for the purposes of computing player compat
   251 	virtual SteamAPICall_t AssociateWithClan( CSteamID steamIDClan ) = 0;
   252 	
   253 	// ask if any of the current players dont want to play with this new player - or vice versa
   254 	virtual SteamAPICall_t ComputeNewPlayerCompatibility( CSteamID steamIDNewPlayer ) = 0;
   255 
   256 };
   257 
   258 #define STEAMGAMESERVER_INTERFACE_VERSION "SteamGameServer011"
   259 
   260 // game server flags
   261 const uint32 k_unServerFlagNone			= 0x00;
   262 const uint32 k_unServerFlagActive		= 0x01;		// server has users playing
   263 const uint32 k_unServerFlagSecure		= 0x02;		// server wants to be secure
   264 const uint32 k_unServerFlagDedicated	= 0x04;		// server is dedicated
   265 const uint32 k_unServerFlagLinux		= 0x08;		// linux build
   266 const uint32 k_unServerFlagPassworded	= 0x10;		// password protected
   267 const uint32 k_unServerFlagPrivate		= 0x20;		// server shouldn't list on master server and
   268 													// won't enforce authentication of users that connect to the server.
   269 													// Useful when you run a server where the clients may not
   270 													// be connected to the internet but you want them to play (i.e LANs)
   271 
   272 
   273 // callbacks
   274 #if defined( VALVE_CALLBACK_PACK_SMALL )
   275 #pragma pack( push, 4 )
   276 #elif defined( VALVE_CALLBACK_PACK_LARGE )
   277 #pragma pack( push, 8 )
   278 #else
   279 #error isteamclient.h must be included
   280 #endif 
   281 
   282 
   283 // client has been approved to connect to this game server
   284 struct GSClientApprove_t
   285 {
   286 	enum { k_iCallback = k_iSteamGameServerCallbacks + 1 };
   287 	CSteamID m_SteamID;
   288 };
   289 
   290 
   291 // client has been denied to connection to this game server
   292 struct GSClientDeny_t
   293 {
   294 	enum { k_iCallback = k_iSteamGameServerCallbacks + 2 };
   295 	CSteamID m_SteamID;
   296 	EDenyReason m_eDenyReason;
   297 	char m_rgchOptionalText[128];
   298 };
   299 
   300 
   301 // request the game server should kick the user
   302 struct GSClientKick_t
   303 {
   304 	enum { k_iCallback = k_iSteamGameServerCallbacks + 3 };
   305 	CSteamID m_SteamID;
   306 	EDenyReason m_eDenyReason;
   307 };
   308 
   309 // NOTE: callback values 4 and 5 are skipped because they are used for old deprecated callbacks, 
   310 // do not reuse them here.
   311 
   312 
   313 // client achievement info
   314 struct GSClientAchievementStatus_t
   315 {
   316 	enum { k_iCallback = k_iSteamGameServerCallbacks + 6 };
   317 	uint64 m_SteamID;
   318 	char m_pchAchievement[128];
   319 	bool m_bUnlocked;
   320 };
   321 
   322 // received when the game server requests to be displayed as secure (VAC protected)
   323 // m_bSecure is true if the game server should display itself as secure to users, false otherwise
   324 struct GSPolicyResponse_t
   325 {
   326 	enum { k_iCallback = k_iSteamUserCallbacks + 15 };
   327 	uint8 m_bSecure;
   328 };
   329 
   330 // GS gameplay stats info
   331 struct GSGameplayStats_t
   332 {
   333 	enum { k_iCallback = k_iSteamGameServerCallbacks + 7 };
   334 	EResult m_eResult;					// Result of the call
   335 	int32	m_nRank;					// Overall rank of the server (0-based)
   336 	uint32	m_unTotalConnects;			// Total number of clients who have ever connected to the server
   337 	uint32	m_unTotalMinutesPlayed;		// Total number of minutes ever played on the server
   338 };
   339 
   340 // send as a reply to RequestUserGroupStatus()
   341 struct GSClientGroupStatus_t
   342 {
   343 	enum { k_iCallback = k_iSteamGameServerCallbacks + 8 };
   344 	CSteamID m_SteamIDUser;
   345 	CSteamID m_SteamIDGroup;
   346 	bool m_bMember;
   347 	bool m_bOfficer;
   348 };
   349 
   350 // Sent as a reply to GetServerReputation()
   351 struct GSReputation_t
   352 {
   353 	enum { k_iCallback = k_iSteamGameServerCallbacks + 9 };
   354 	EResult	m_eResult;				// Result of the call;
   355 	uint32	m_unReputationScore;	// The reputation score for the game server
   356 	bool	m_bBanned;				// True if the server is banned from the Steam
   357 									// master servers
   358 
   359 	// The following members are only filled out if m_bBanned is true. They will all 
   360 	// be set to zero otherwise. Master server bans are by IP so it is possible to be
   361 	// banned even when the score is good high if there is a bad server on another port.
   362 	// This information can be used to determine which server is bad.
   363 
   364 	uint32	m_unBannedIP;		// The IP of the banned server
   365 	uint16	m_usBannedPort;		// The port of the banned server
   366 	uint64	m_ulBannedGameID;	// The game ID the banned server is serving
   367 	uint32	m_unBanExpires;		// Time the ban expires, expressed in the Unix epoch (seconds since 1/1/1970)
   368 };
   369 
   370 // Sent as a reply to AssociateWithClan()
   371 struct AssociateWithClanResult_t
   372 {
   373 	enum { k_iCallback = k_iSteamGameServerCallbacks + 10 };
   374 	EResult	m_eResult;				// Result of the call;
   375 };
   376 
   377 // Sent as a reply to ComputeNewPlayerCompatibility()
   378 struct ComputeNewPlayerCompatibilityResult_t
   379 {
   380 	enum { k_iCallback = k_iSteamGameServerCallbacks + 11 };
   381 	EResult	m_eResult;				// Result of the call;
   382 	int m_cPlayersThatDontLikeCandidate;
   383 	int m_cPlayersThatCandidateDoesntLike;
   384 	int m_cClanPlayersThatDontLikeCandidate;
   385 	CSteamID m_SteamIDCandidate;
   386 };
   387 
   388 
   389 #pragma pack( pop )
   390 
   391 #endif // ISTEAMGAMESERVER_H