public/steam/isteamutils.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 utility functions in Steam
     4 //
     5 //=============================================================================
     6 
     7 #ifndef ISTEAMUTILS_H
     8 #define ISTEAMUTILS_H
     9 #ifdef _WIN32
    10 #pragma once
    11 #endif
    12 
    13 #include "isteamclient.h"
    14 
    15 
    16 // Steam API call failure results
    17 enum ESteamAPICallFailure
    18 {
    19 	k_ESteamAPICallFailureNone = -1,			// no failure
    20 	k_ESteamAPICallFailureSteamGone = 0,		// the local Steam process has gone away
    21 	k_ESteamAPICallFailureNetworkFailure = 1,	// the network connection to Steam has been broken, or was already broken
    22 	// SteamServersDisconnected_t callback will be sent around the same time
    23 	// SteamServersConnected_t will be sent when the client is able to talk to the Steam servers again
    24 	k_ESteamAPICallFailureInvalidHandle = 2,	// the SteamAPICall_t handle passed in no longer exists
    25 	k_ESteamAPICallFailureMismatchedCallback = 3,// GetAPICallResult() was called with the wrong callback type for this API call
    26 };
    27 
    28 
    29 // Input modes for the Big Picture gamepad text entry
    30 enum EGamepadTextInputMode
    31 {
    32 	k_EGamepadTextInputModeNormal = 0,
    33 	k_EGamepadTextInputModePassword = 1
    34 };
    35 
    36 
    37 // Controls number of allowed lines for the Big Picture gamepad text entry
    38 enum EGamepadTextInputLineMode
    39 {
    40 	k_EGamepadTextInputLineModeSingleLine = 0,
    41 	k_EGamepadTextInputLineModeMultipleLines = 1
    42 };
    43 
    44 
    45 // function prototype for warning message hook
    46 #if defined( POSIX )
    47 #define __cdecl
    48 #endif
    49 extern "C" typedef void (__cdecl *SteamAPIWarningMessageHook_t)(int, const char *);
    50 
    51 //-----------------------------------------------------------------------------
    52 // Purpose: interface to user independent utility functions
    53 //-----------------------------------------------------------------------------
    54 class ISteamUtils
    55 {
    56 public:
    57 	// return the number of seconds since the user 
    58 	virtual uint32 GetSecondsSinceAppActive() = 0;
    59 	virtual uint32 GetSecondsSinceComputerActive() = 0;
    60 
    61 	// the universe this client is connecting to
    62 	virtual EUniverse GetConnectedUniverse() = 0;
    63 
    64 	// Steam server time - in PST, number of seconds since January 1, 1970 (i.e unix time)
    65 	virtual uint32 GetServerRealTime() = 0;
    66 
    67 	// returns the 2 digit ISO 3166-1-alpha-2 format country code this client is running in (as looked up via an IP-to-location database)
    68 	// e.g "US" or "UK".
    69 	virtual const char *GetIPCountry() = 0;
    70 
    71 	// returns true if the image exists, and valid sizes were filled out
    72 	virtual bool GetImageSize( int iImage, uint32 *pnWidth, uint32 *pnHeight ) = 0;
    73 
    74 	// returns true if the image exists, and the buffer was successfully filled out
    75 	// results are returned in RGBA format
    76 	// the destination buffer size should be 4 * height * width * sizeof(char)
    77 	virtual bool GetImageRGBA( int iImage, uint8 *pubDest, int nDestBufferSize ) = 0;
    78 
    79 	// returns the IP of the reporting server for valve - currently only used in Source engine games
    80 	virtual bool GetCSERIPPort( uint32 *unIP, uint16 *usPort ) = 0;
    81 
    82 	// return the amount of battery power left in the current system in % [0..100], 255 for being on AC power
    83 	virtual uint8 GetCurrentBatteryPower() = 0;
    84 
    85 	// returns the appID of the current process
    86 	virtual uint32 GetAppID() = 0;
    87 
    88 	// Sets the position where the overlay instance for the currently calling game should show notifications.
    89 	// This position is per-game and if this function is called from outside of a game context it will do nothing.
    90 	virtual void SetOverlayNotificationPosition( ENotificationPosition eNotificationPosition ) = 0;
    91 
    92 	// API asynchronous call results
    93 	// can be used directly, but more commonly used via the callback dispatch API (see steam_api.h)
    94 	virtual bool IsAPICallCompleted( SteamAPICall_t hSteamAPICall, bool *pbFailed ) = 0;
    95 	virtual ESteamAPICallFailure GetAPICallFailureReason( SteamAPICall_t hSteamAPICall ) = 0;
    96 	virtual bool GetAPICallResult( SteamAPICall_t hSteamAPICall, void *pCallback, int cubCallback, int iCallbackExpected, bool *pbFailed ) = 0;
    97 
    98 	// this needs to be called every frame to process matchmaking results
    99 	// redundant if you're already calling SteamAPI_RunCallbacks()
   100 	virtual void RunFrame() = 0;
   101 
   102 	// returns the number of IPC calls made since the last time this function was called
   103 	// Used for perf debugging so you can understand how many IPC calls your game makes per frame
   104 	// Every IPC call is at minimum a thread context switch if not a process one so you want to rate
   105 	// control how often you do them.
   106 	virtual uint32 GetIPCCallCount() = 0;
   107 
   108 	// API warning handling
   109 	// 'int' is the severity; 0 for msg, 1 for warning
   110 	// 'const char *' is the text of the message
   111 	// callbacks will occur directly after the API function is called that generated the warning or message
   112 	virtual void SetWarningMessageHook( SteamAPIWarningMessageHook_t pFunction ) = 0;
   113 
   114 	// Returns true if the overlay is running & the user can access it. The overlay process could take a few seconds to
   115 	// start & hook the game process, so this function will initially return false while the overlay is loading.
   116 	virtual bool IsOverlayEnabled() = 0;
   117 
   118 	// Normally this call is unneeded if your game has a constantly running frame loop that calls the 
   119 	// D3D Present API, or OGL SwapBuffers API every frame.
   120 	//
   121 	// However, if you have a game that only refreshes the screen on an event driven basis then that can break 
   122 	// the overlay, as it uses your Present/SwapBuffers calls to drive it's internal frame loop and it may also
   123 	// need to Present() to the screen any time an even needing a notification happens or when the overlay is
   124 	// brought up over the game by a user.  You can use this API to ask the overlay if it currently need a present
   125 	// in that case, and then you can check for this periodically (roughly 33hz is desirable) and make sure you
   126 	// refresh the screen with Present or SwapBuffers to allow the overlay to do it's work.
   127 	virtual bool BOverlayNeedsPresent() = 0;
   128 
   129 #ifndef _PS3
   130 	// Asynchronous call to check if an executable file has been signed using the public key set on the signing tab
   131 	// of the partner site, for example to refuse to load modified executable files.  
   132 	// The result is returned in CheckFileSignature_t.
   133 	//   k_ECheckFileSignatureNoSignaturesFoundForThisApp - This app has not been configured on the signing tab of the partner site to enable this function.
   134 	//   k_ECheckFileSignatureNoSignaturesFoundForThisFile - This file is not listed on the signing tab for the partner site.
   135 	//   k_ECheckFileSignatureFileNotFound - The file does not exist on disk.
   136 	//   k_ECheckFileSignatureInvalidSignature - The file exists, and the signing tab has been set for this file, but the file is either not signed or the signature does not match.
   137 	//   k_ECheckFileSignatureValidSignature - The file is signed and the signature is valid.
   138 	virtual SteamAPICall_t CheckFileSignature( const char *szFileName ) = 0;
   139 #endif
   140 
   141 #ifdef _PS3
   142 	virtual void PostPS3SysutilCallback( uint64_t status, uint64_t param, void* userdata ) = 0;
   143 	virtual bool BIsReadyToShutdown() = 0;
   144 	virtual bool BIsPSNOnline() = 0;
   145 
   146 	// Call this with localized strings for the language the game is running in, otherwise default english
   147 	// strings will be used by Steam.
   148 	virtual void SetPSNGameBootInviteStrings( const char *pchSubject, const char *pchBody ) = 0;
   149 #endif
   150 
   151 	// Activates the Big Picture text input dialog which only supports gamepad input
   152 	virtual bool ShowGamepadTextInput( EGamepadTextInputMode eInputMode, EGamepadTextInputLineMode eLineInputMode, const char *pchDescription, uint32 unCharMax ) = 0;
   153 
   154 	// Returns previously entered text & length
   155 	virtual uint32 GetEnteredGamepadTextLength() = 0;
   156 	virtual bool GetEnteredGamepadTextInput( char *pchText, uint32 cchText ) = 0;	
   157 
   158 	// returns the language the steam client is running in, you probably want ISteamApps::GetCurrentGameLanguage instead, this is for very special usage cases
   159 	virtual const char *GetSteamUILanguage() = 0;
   160 };
   161 
   162 #define STEAMUTILS_INTERFACE_VERSION "SteamUtils006"
   163 
   164 
   165 // callbacks
   166 #if defined( VALVE_CALLBACK_PACK_SMALL )
   167 #pragma pack( push, 4 )
   168 #elif defined( VALVE_CALLBACK_PACK_LARGE )
   169 #pragma pack( push, 8 )
   170 #else
   171 #error isteamclient.h must be included
   172 #endif 
   173 
   174 //-----------------------------------------------------------------------------
   175 // Purpose: The country of the user changed
   176 //-----------------------------------------------------------------------------
   177 struct IPCountry_t
   178 {
   179 	enum { k_iCallback = k_iSteamUtilsCallbacks + 1 };
   180 };
   181 
   182 
   183 //-----------------------------------------------------------------------------
   184 // Purpose: Fired when running on a laptop and less than 10 minutes of battery is left, fires then every minute
   185 //-----------------------------------------------------------------------------
   186 struct LowBatteryPower_t
   187 {
   188 	enum { k_iCallback = k_iSteamUtilsCallbacks + 2 };
   189 	uint8 m_nMinutesBatteryLeft;
   190 };
   191 
   192 
   193 //-----------------------------------------------------------------------------
   194 // Purpose: called when a SteamAsyncCall_t has completed (or failed)
   195 //-----------------------------------------------------------------------------
   196 struct SteamAPICallCompleted_t
   197 {
   198 	enum { k_iCallback = k_iSteamUtilsCallbacks + 3 };
   199 	SteamAPICall_t m_hAsyncCall;
   200 };
   201 
   202 
   203 //-----------------------------------------------------------------------------
   204 // called when Steam wants to shutdown
   205 //-----------------------------------------------------------------------------
   206 struct SteamShutdown_t
   207 {
   208 	enum { k_iCallback = k_iSteamUtilsCallbacks + 4 };
   209 };
   210 
   211 //-----------------------------------------------------------------------------
   212 // results for CheckFileSignature
   213 //-----------------------------------------------------------------------------
   214 enum ECheckFileSignature
   215 {
   216 	k_ECheckFileSignatureInvalidSignature = 0,
   217 	k_ECheckFileSignatureValidSignature = 1,
   218 	k_ECheckFileSignatureFileNotFound = 2,
   219 	k_ECheckFileSignatureNoSignaturesFoundForThisApp = 3,
   220 	k_ECheckFileSignatureNoSignaturesFoundForThisFile = 4,
   221 };
   222 
   223 //-----------------------------------------------------------------------------
   224 // callback for CheckFileSignature
   225 //-----------------------------------------------------------------------------
   226 struct CheckFileSignature_t
   227 {
   228 	enum { k_iCallback = k_iSteamUtilsCallbacks + 5 };
   229 	ECheckFileSignature m_eCheckFileSignature;
   230 };
   231 
   232 #ifdef _PS3
   233 //-----------------------------------------------------------------------------
   234 // callback for NetCtlNetStartDialog finishing on PS3
   235 //-----------------------------------------------------------------------------
   236 struct NetStartDialogFinished_t
   237 {
   238 	enum { k_iCallback = k_iSteamUtilsCallbacks + 6 };
   239 };
   240 
   241 //-----------------------------------------------------------------------------
   242 // callback for NetCtlNetStartDialog unloaded on PS3
   243 //-----------------------------------------------------------------------------
   244 struct NetStartDialogUnloaded_t
   245 {
   246 	enum { k_iCallback = k_iSteamUtilsCallbacks + 7 };
   247 };
   248 
   249 //-----------------------------------------------------------------------------
   250 // callback for system menu closing on PS3 - should trigger resyncronizing friends list, etc.
   251 //-----------------------------------------------------------------------------
   252 struct PS3SystemMenuClosed_t
   253 {
   254 	enum { k_iCallback = k_iSteamUtilsCallbacks + 8 };
   255 };
   256 
   257 //-----------------------------------------------------------------------------
   258 // callback for NP message being selected by user on PS3 - should trigger handling of message if it's a lobby invite, etc.
   259 //-----------------------------------------------------------------------------
   260 struct PS3NPMessageSelected_t
   261 {
   262 	enum { k_iCallback = k_iSteamUtilsCallbacks + 9 };
   263 	uint32 dataid;
   264 };
   265 
   266 //-----------------------------------------------------------------------------
   267 // callback for when the PS3 keyboard dialog closes
   268 //-----------------------------------------------------------------------------
   269 struct PS3KeyboardDialogFinished_t
   270 {
   271 	enum { k_iCallback = k_iSteamUtilsCallbacks + 10 };
   272 };
   273 
   274 // k_iSteamUtilsCallbacks + 11 is taken
   275 
   276 //-----------------------------------------------------------------------------
   277 // callback for PSN status changing on PS3
   278 //-----------------------------------------------------------------------------
   279 struct PS3PSNStatusChange_t
   280 {
   281 	enum { k_iCallback = k_iSteamUtilsCallbacks + 12 };
   282 	bool m_bPSNOnline;
   283 };
   284 
   285 #endif
   286 
   287 // k_iSteamUtilsCallbacks + 13 is taken
   288 
   289 
   290 //-----------------------------------------------------------------------------
   291 // Big Picture gamepad text input has been closed
   292 //-----------------------------------------------------------------------------
   293 struct GamepadTextInputDismissed_t
   294 {
   295 	enum { k_iCallback = k_iSteamUtilsCallbacks + 14 };
   296 	bool m_bSubmitted;										// true if user entered & accepted text (Call ISteamUtils::GetEnteredGamepadTextInput() for text), false if canceled input
   297 	uint32 m_unSubmittedText;
   298 };
   299 
   300 // k_iSteamUtilsCallbacks + 15 is taken
   301 
   302 #pragma pack( pop )
   303 
   304 #endif // ISTEAMUTILS_H