Unaffiliated

Home Documentation & Help
Steamworks Documentation
ISteamUtils Interface
Interface which provides access to a range of miscellaneous utility functions.

Member Functions

Member functions for ISteamUtils are called through the global accessor function SteamUtils().

BOverlayNeedsPresent

bool BOverlayNeedsPresent();
Checks if the Overlay needs a present. Only required if using event driven render updates.

Typically this call is unneeded if your game has a constantly running frame loop that calls the D3D Present API, or OGL SwapBuffers API every frame as is the case in most games. However, if you have a game that only refreshes the screen on an event driven basis then that can break the overlay, as it uses your Present/SwapBuffers calls to drive it's internal frame loop and it may also need to Present() to the screen any time a notification happens or when the overlay is brought up over the game by a user. You can use this API to ask the overlay if it currently need a present in that case, and then you can check for this periodically (roughly 33hz is desirable) and make sure you refresh the screen with Present or SwapBuffers to allow the overlay to do it's work.

Returns: bool
true if the overlay needs you to refresh the screen, otherwise false.

CheckFileSignature

SteamAPICall_t CheckFileSignature( const char *szFileName );
NameTypeDescription
szFileNameconst char *.

Deprecated.

Returns: SteamAPICall_t to be used with a CheckFileSignature_t call result.

GetAPICallFailureReason

ESteamAPICallFailure GetAPICallFailureReason( SteamAPICall_t hSteamAPICall );
NameTypeDescription
hSteamAPICallSteamAPICall_tThe Steam API Call handle to check the failure for.

Used to get the failure reason of a call result.

The primary usage for this function is debugging. The failure reasons are typically out of your control and tend to not be very important. Just keep retrying your API Call until it works.

Returns: ESteamAPICallFailure
[type]ESteamAPICallFailure[/type]

See Also: IsAPICallCompleted, GetAPICallResult

Example:
void CHTMLSurface::OnBrowserReady( HTML_BrowserReady_t *pBrowserReady, bool bIOFailure ) { if ( bIOFailure ) { SteamUtils()->GetAPICallFailureReason( handle ); // handle must be stored separately. return; } }

GetAPICallResult

bool GetAPICallResult( SteamAPICall_t hSteamAPICall, void *pCallback, int cubCallback, int iCallbackExpected, bool *pbFailed );
NameTypeDescription
hSteamAPICallSteamAPICall_tThe handle to the API Call.
pCallbackvoid *Returns the callback into the preallocated memory provided.
cubCallbackintThe size of pCallback that you are passing in.
iCallbackExpectedintThe k_iCallback number associated with the callback.
pbFailedbool *Returns if the API call has encountered a failure.

Gets the content of a completed API Call. Provided for the backend of the CallResult wrapper.

It's generally not recommended that you use this manually.

Returns: bool
true upon success if the API Call is valid and has completed, otherwise false.

If the call is successful, it copies the callback into pCallback and returns failures in pbFailed.

See Also: IsAPICallCompleted, GetAPICallFailureReason

GetAppID

uint32 GetAppID();
Gets the App ID of the current process.

Returns: uint32
Returns the AppId.

GetConnectedUniverse

EUniverse GetConnectedUniverse();
Gets the universe that the current client is connecting to. (Valve use only.)

Returns: EUniverse
[type]EUniverse[/type]

GetCSERIPPort

bool GetCSERIPPort( uint32 *unIP, uint16 *usPort );
NameTypeDescription
unIPuint32 *Returns the IP that the client is connected to.
usPortuint16 *Returns the port that the client is connected to.

Gets the IP of the reporting server for valve - currently only used in Source engine games

Returns: bool
Returns true if the user is currently connected; otherwise, false.

GetCurrentBatteryPower

uint8 GetCurrentBatteryPower();
Gets the current amount of battery power on the computer.

Returns: uint8
The current battery power ranging between [0..100]%. Returns 255 when the user is on AC power.

GetEnteredGamepadTextInput

bool GetEnteredGamepadTextInput( char *pchText, uint32 cchText );
NameTypeDescription
pchTextchar *A preallocated buffer to copy the text input string into.
cchTextuint32The size of the pchText buffer.

Gets the gamepad text input from the Big Picture overlay.

This must be called within the GamepadTextInputDismissed_t callback, and only if GamepadTextInputDismissed_t.m_bSubmitted is true.

Provides the text input as UTF8.

Returns: bool
true if there was text to receive and cchText is the same size as GamepadTextInputDismissed_t.m_unSubmittedText; otherwise, false.

See Also: ShowGamepadTextInput, GetEnteredGamepadTextLength

Example:
void OnGamepadTextInputDismissed_t( GamepadTextInputDismissed_t* pCallback ) { // The user canceled, if ( !pCallback.m_bSubmitted ) return; // Use some max input length that we passed into ShowGamepadTextInput, +1 for the null terminator. const uint32 MAX_INPUT_LENGTH = 64 + 1; uint32 length = SteamUtils()->GetEnteredGamepadTextLength(); char* szTextInput[MAX_INPUT_LENGTH]; bool success = SteamUtils()->GetEnteredGamepadTextInput( szTextInput, length ); if ( !success ) { // Log an error. This should only ever happen if length is > MaxInputLength return; } // Display the updated string }

GetEnteredGamepadTextLength

uint32 GetEnteredGamepadTextLength();
Gets the length of the gamepad text input from the Big Picture overlay.

This must be called within the GamepadTextInputDismissed_t callback, and only if GamepadTextInputDismissed_t.m_bSubmitted is true.

Returns: uint32


See Also: ShowGamepadTextInput, GetEnteredGamepadTextInput

Example:
void OnGamepadTextInputDismissed_t( GamepadTextInputDismissed_t* pCallback ) { // The user canceled, if ( !pCallback.m_bSubmitted ) return; // Use some max input length that we passed into ShowGamepadTextInput, +1 for the null terminator. const uint32 MAX_INPUT_LENGTH = 64 + 1; uint32 length = SteamUtils()->GetEnteredGamepadTextLength(); const char* szTextInput[MAX_INPUT_LENGTH]; bool success = SteamUtils()->GetEnteredGamepadTextInput( szTextInput, length ); if ( !success ) { // Log an error. This should only ever happen if length is > MaxInputLength return; } // Display the updated string }

GetImageRGBA

bool GetImageRGBA( int iImage, uint8 *pubDest, int nDestBufferSize );
NameTypeDescription
iImageintThe handle to the image that will be obtained.
pubDestuint8 *The buffer that will be filled.
nDestBufferSizeintThe total size of the pubDest buffer.

Gets the image bytes from an image handle.

Prior to calling this you must get the size of the image by calling GetImageSize so that you can create your buffer with an appropriate size. You can then allocate your buffer with the width and height as: width * height * 4. The image is provided in RGBA format. This call can be somewhat expensive as it converts from the compressed type (JPG, PNG, TGA) and provides no internal caching of returned buffer, thus it is highly recommended to only call this once per image handle and cache the result. This function is only used for Steam Avatars and Achievement images and those are not expected to change mid game.

Returns: bool
true upon success if the image handle is valid and the buffer was filled out, otherwise false.

See Also: ISteamFriends::GetSmallFriendAvatar, ISteamFriends::GetMediumFriendAvatar, ISteamFriends::GetLargeFriendAvatar, ISteamUserStats::GetAchievementIcon

Example:
HGAMETEXTURE GetSteamImageAsTexture( int iImage ) { HGAMETEXTURE hTexture = 0; // You should first check if you have already cached this image using something like a dictionary/map // with iImage as the key and then return the texture handle associated with it if it exists. // If it doesn't exist, continue on, and add the texture to the map before returning at the end of the function. // If we have to check the size of the image. uint32 uAvatarWidth, uAvatarHeight; bool success SteamUtils()->GetImageSize( iImage, &uAvatarWidth, &uAvatarHeight ); if ( !success ) { // Log a warning message. return hTexture; } // Get the actual raw RGBA data from Steam and turn it into a texture in our game engine const int uImageSizeInBytes = uAvatarWidth * uAvatarHeight * 4; uint8 *pAvatarRGBA = new uint8[ uImageSizeInBytes ]; success = SteamUtils()->GetImageRGBA( iImage, pAvatarRGBA, uImageSizeInBytes ); if( !success ) { // Do something to convert the RGBA texture into your internal texture format for displaying. // hTexture = m_pGameEngine->HCreateTexture( pAvatarRGBA, uAvatarWidth, uAvatarHeight ); // And add the texture to the cache } // Don't forget to free the memory! delete[] pAvatarRGBA; return hTexture; }

GetImageSize

bool GetImageSize( int iImage, uint32 *pnWidth, uint32 *pnHeight );
NameTypeDescription
iImageintThe image handle to get the size for.
pnWidthuint32 *Returns the width of the image.
pnHeightuint32 *Returns the height of the image.

Gets the size of a Steam image handle.

This must be called before calling GetImageRGBA to create an appropriately sized buffer that will be filled with the raw image data.

Returns: bool
true upon success if the image handle is valid and the sizes were filled out, otherwise false.

See Also: ISteamFriends::GetSmallFriendAvatar, ISteamFriends::GetMediumFriendAvatar, ISteamFriends::GetLargeFriendAvatar, ISteamUserStats::GetAchievementIcon

GetIPCCallCount

uint32 GetIPCCallCount();
Returns the number of IPC calls made since the last time this function was called.

Used for perf debugging so you can determine how many IPC (Inter-Process Communication) calls your game makes per frame
Every IPC call is at minimum a thread context switch if not a process one so you want to rate control how often you do them.

Returns: uint32

GetIPCountry

const char * GetIPCountry();
Returns the 2 digit ISO 3166-1-alpha-2 format country code which client is running in.
e.g "US" or "UK".

This is looked up via an IP-to-location database.

Returns: const char *

GetSecondsSinceAppActive

uint32 GetSecondsSinceAppActive();
Returns the number of seconds since the application was active.

Returns: uint32

GetSecondsSinceComputerActive

uint32 GetSecondsSinceComputerActive();
Returns the number of seconds since the user last moved the mouse.

Returns: uint32

GetServerRealTime

uint32 GetServerRealTime();
Returns the Steam server time in Unix epoch format. (Number of seconds since Jan 1, 1970 UTC)

Returns: uint32

GetSteamUILanguage

const char * GetSteamUILanguage();
Returns the language the steam client is running in.

You probably want ISteamApps::GetCurrentGameLanguage instead, this should only be used in very special cases.

For a full list of languages see Supported Languages.

Returns: const char *


See Also: ISteamApps::GetCurrentGameLanguage, ISteamApps::GetAvailableGameLanguages

IsAPICallCompleted

bool IsAPICallCompleted( SteamAPICall_t hSteamAPICall, bool *pbFailed );
NameTypeDescription
hSteamAPICallSteamAPICall_tThe API Call handle to check.
pbFailedbool *Returns whether the API call has encountered a failure (true) or not (false).

Checks if an API Call is completed. Provides the backend of the CallResult wrapper.

It's generally not recommended that you use this yourself.

Returns: bool
true if the API Call is valid and has completed, otherwise false.

See Also: GetAPICallResult, GetAPICallFailureReason

IsOverlayEnabled

bool IsOverlayEnabled();
Checks if the Steam Overlay is running & the user can access it.

The overlay process could take a few seconds to start & hook the game process, so this function will initially return false while the overlay is loading.

Returns: bool

IsSteamInBigPictureMode

bool IsSteamInBigPictureMode();
Checks if Steam & the Steam Overlay are running in Big Picture mode.

Games must be launched through the Steam client to enable the Big Picture overlay.
During development, a game can be added as a non-steam game to the developers library to test this feature.

Returns: bool
true if the Big Picture overlay is available; otherwise, false.
This will always return false if your app is not the 'game' application type.

IsSteamRunningInVR

bool IsSteamRunningInVR();
Checks if Steam is running in VR mode.

Returns: bool
true if Steam itself is running in VR mode; otherwise, false.

IsVRHeadsetStreamingEnabled

bool IsVRHeadsetStreamingEnabled();
Checks if the HMD view will be streamed via Steam In-Home Streaming.

Returns: bool
true if VR is enabled and the HMD view is currently being streamed; otherwise, false.

See Also: SetVRHeadsetStreamingEnabled

SetOverlayNotificationInset

void SetOverlayNotificationInset( int nHorizontalInset, int nVerticalInset );
NameTypeDescription
nHorizontalInsetintThe horizontal (left-right) distance in pixels from the corner.
nVerticalInsetintThe vertical (up-down) distance in pixels from the corner.

Sets the inset of the overlay notification from the corner specified by SetOverlayNotificationPosition.

A value of (0, 0) resets the position into the corner.

This position is per-game and is reset each launch.

SetOverlayNotificationPosition

void SetOverlayNotificationPosition( ENotificationPosition eNotificationPosition );
NameTypeDescription
eNotificationPositionENotificationPosition

Sets which corner the Steam overlay notification popup should display itself in.

You can also set the distance from the specified corner by using SetOverlayNotificationInset.

This position is per-game and is reset each launch.

SetVRHeadsetStreamingEnabled

void SetVRHeadsetStreamingEnabled( bool bEnabled );
NameTypeDescription
bEnabledboolTurns VR HMD Streaming on (true) or off (false).

Set whether the HMD content will be streamed via Steam In-Home Streaming.

If this is enabled, then the scene in the HMD headset will be streamed, and remote input will not be allowed. Otherwise if this is disabled, then the application window will be streamed instead, and remote input will be allowed. VR games default to enabled unless "VRHeadsetStreaming" "0" is in the extended appinfo for a game.

This is useful for games that have asymmetric multiplayer gameplay.

See Also: IsVRHeadsetStreamingEnabled

SetWarningMessageHook

void SetWarningMessageHook( SteamAPIWarningMessageHook_t pFunction );
NameTypeDescription
pFunctionSteamAPIWarningMessageHook_tFunction pointer to the callback function.

Sets a warning message hook to receive SteamAPI warnings and info messages in a callback function.

The function prototype must match the definition in SteamAPIWarningMessageHook_t. This includes the extern "C" linkage and __cdecl calling convention.

'int nSeverity' is the severity; 0 for msg, 1 for warning. If you are running in through a debugger only warnings will be sent. If you add -debug_steamapi to the command-line then informational messages will also be sent.
'const char * pchDebugText' is the text of the message.
Callbacks will occur directly after the API function is called that generated the warning or message

Passing NULL will unhook.

Example:
extern "C" void __cdecl SteamAPIDebugTextHook( int nSeverity, const char *pchDebugText ) { ::OutputDebugString( pchDebugText ); if ( nSeverity >= 1 ) { // place to set a breakpoint for catching API errors int x = 3; x = x; } } void EnableWarningMessageHook() { SteamUtils()->SetWarningMessageHook( &SteamAPIDebugTextHook ); }

ShowGamepadTextInput

bool ShowGamepadTextInput( EGamepadTextInputMode eInputMode, EGamepadTextInputLineMode eLineInputMode, const char *pchDescription, uint32 unCharMax, const char *pchExistingText );
NameTypeDescription
eInputModeEGamepadTextInputModeSelects the input mode to use, either Normal or Password (hidden text)
eLineInputModeEGamepadTextInputLineModeControls whether to use single or multi line input.
pchDescriptionconst char *Sets the description that should inform the user what the input dialog is for.
unCharMaxuint32The maximum number of characters that the user can input.
pchExistingTextconst char *Sets the preexisting text which the user can edit.

Activates the Big Picture text input dialog which only supports gamepad input.

Returns: bool
true if the big picture overlay is running; otherwise, false.

See Also: GetEnteredGamepadTextLength, GetEnteredGamepadTextInput

StartVRDashboard

void StartVRDashboard();
Asks Steam to create and render the OpenVR dashboard.

Callbacks

These are callbacks which can be fired by calling SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ISteamUtils.

CheckFileSignature_t

CallResult for CheckFileSignature.

NameTypeDescription
m_eCheckFileSignatureECheckFileSignatureContains the result of the file signature check.
k_ECheckFileSignatureNoSignaturesFoundForThisApp - This app has not been configured on the signing tab of the partner site to enable this function.
k_ECheckFileSignatureNoSignaturesFoundForThisFile - This file is not listed on the signing tab for the partner site.k_ECheckFileSignatureFileNotFound - The file does not exist on disk.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.
k_ECheckFileSignatureValidSignature - The file is signed and the signature is valid.

Associated Functions: CheckFileSignature

GamepadTextInputDismissed_t

Called when the big picture gamepad text input has been closed.

NameTypeDescription
m_bSubmittedbooltrue if user entered & accepted text (Call GetEnteredGamepadTextInput to receive the text), false if input was canceled.
m_unSubmittedTextuint32Contains the length in bytes if there was text submitted.

IPCountry_t

Called when the country of the user changed. The country should be updated with GetIPCountry.

This callback has no fields.

LowBatteryPower_t

Called when running on a laptop and less than 10 minutes of battery is left, and then fires then every minute afterwards.

NameTypeDescription
m_nMinutesBatteryLeftuint8The estimated amount of battery life left in minutes.

SteamAPICallCompleted_t

Called when a SteamAPICall_t has completed (or failed)

NameTypeDescription
m_hAsyncCallSteamAPICall_tThe handle of the Steam API Call that completed.
m_iCallbackintThis is the k_iCallback constant which uniquely identifies the completed callback.
m_cubParamuint32The size in bytes of the completed callback.

SteamShutdown_t

Called when Steam wants to shutdown.

This callback has no fields.

Enums

These are enums which are defined for use with ISteamUtils.

ECheckFileSignature

The result of a call to CheckFileSignature

NameValueDescription
k_ECheckFileSignatureInvalidSignature0
k_ECheckFileSignatureValidSignature1
k_ECheckFileSignatureFileNotFound2
k_ECheckFileSignatureNoSignaturesFoundForThisApp3
k_ECheckFileSignatureNoSignaturesFoundForThisFile4

EGamepadTextInputLineMode

Controls number of allowed lines for the Big Picture gamepad text entry

NameValueDescription
k_EGamepadTextInputLineModeSingleLine0
k_EGamepadTextInputLineModeMultipleLines1

EGamepadTextInputMode

Input modes for the Big Picture gamepad text entry

NameValueDescription
k_EGamepadTextInputModeNormal0
k_EGamepadTextInputModePassword1

ESteamAPICallFailure

Steam API call failure results returned by GetAPICallFailureReason.

NameValueDescription
k_ESteamAPICallFailureNone-1No failure.
k_ESteamAPICallFailureSteamGone0The local Steam process has stopped responding, it may have been forcefully closed or is frozen.
k_ESteamAPICallFailureNetworkFailure1The network connection to the Steam servers has been lost, or was already broken.
A SteamServersDisconnected_t callback will be sent around the same time, and a SteamServersConnected_t callback will be sent when the client is able to talk to the Steam servers again.
k_ESteamAPICallFailureInvalidHandle2The SteamAPICall_t handle passed in no longer exists.
k_ESteamAPICallFailureMismatchedCallback3GetAPICallResult was called with the wrong callback type for this API call.

Constants

These are constants which are defined for use with ISteamUtils.

NameTypeValueDescription
STEAMUTILS_INTERFACE_VERSIONconst char *"SteamUtils009"