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