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

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 its work.

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

CheckFileSignature

Name	Type	Description
szFileName	const char *	.

Deprecated.

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

GetAPICallFailureReason

Name	Type	Description
hSteamAPICall	SteamAPICall_t	The 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:

GetAPICallResult

Name	Type	Description
hSteamAPICall	SteamAPICall_t	The handle to the API Call.
pCallback	void *	Returns the callback into the preallocated memory provided.
cubCallback	int	The size of pCallback that you are passing in.
iCallbackExpected	int	The k_iCallback number associated with the callback.
pbFailed	bool *	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

Gets the App ID of the current process.

Returns: uint32
Returns the AppId.

GetConnectedUniverse

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

Returns: EUniverse
[type]EUniverse[/type]

GetCSERIPPort

Name	Type	Description
unIP	uint32 *	Returns the IP that the client is connected to.
usPort	uint16 *	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

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

Name	Type	Description
pchText	char *	A preallocated buffer to copy the text input string into.
cchText	uint32	The 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 UTF-8.

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:

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:

GetImageRGBA

Name	Type	Description
iImage	int	The handle to the image that will be obtained.
pubDest	uint8 *	The buffer that will be filled.
nDestBufferSize	int	The 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:

GetImageSize

Name	Type	Description
iImage	int	The image handle to get the size for.
pnWidth	uint32 *	Returns the width of the image.
pnHeight	uint32 *	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

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

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

Returns the number of seconds since the application was active.

Returns: uint32

GetSecondsSinceComputerActive

Returns the number of seconds since the user last moved the mouse.

Returns: uint32

GetServerRealTime

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

Returns: uint32

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

Name	Type	Description
hSteamAPICall	SteamAPICall_t	The API Call handle to check.
pbFailed	bool *	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

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

IsSteamChinaLauncher

Returns whether the current launcher is a Steam China launcher. You can cause the client to behave as the Steam China launcher by adding -dev -steamchina to the command line when running Steam.

InitFilterText

Initializes text filtering, loading dictionaries for the language the game is running in.

Users can customize the text filter behavior in their Steam Account preferences

Returns: bool
true if initialization succeeds, false if filtering is unavailable for the game's language, in which case FilterText() will act as a passthrough.

See Also: FilterText

FilterText

Name	Type	Description
eContext	ETextFilteringContext	the type of content in the input string
sourceSteamID	CSteamID	the Steam ID that is the source of the input string (e.g. the player with the name, or who said the chat text)
pchInputText	const char*	the input string that should be filtered, which can be ASCII or UTF-8
pchOutFilteredText	char*	where the output will be placed, even if no filtering is performed
nByteSizeOutFilteredText	uint32	the size (in bytes) of pchOutFilteredText, should be at least strlen(pchInputText)+1

Filters the provided input message and places the filtered result into pchOutFilteredText. Legally required filtering is always applied. Additional filtering may occur, based on the context and user settings.

Returns: int
Returns the number of characters (not bytes) filtered.

See Also: InitFilterText

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 developer's 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

Checks if Steam is running in VR mode.

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

IsVRHeadsetStreamingEnabled

Checks if the HMD view is being streamed via Steam Remote Play.

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

See Also: SetVRHeadsetStreamingEnabled

IsSteamRunningOnSteamDeck

Checks if Steam is running on a Steam Deck device.

Returns: bool
true if Steam itself is running on a Steam Deck device; otherwise, false.

SetOverlayNotificationInset

Name	Type	Description
nHorizontalInset	int	The horizontal (left-right) distance in pixels from the corner.
nVerticalInset	int	The 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

Name	Type	Description
eNotificationPosition	ENotificationPosition

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

Name	Type	Description
bEnabled	bool	Turns VR HMD Streaming on (true) or off (false).

Set whether the HMD content will be streamed via Steam Remote Play.

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

Name	Type	Description
pFunction	SteamAPIWarningMessageHook_t	Function 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:

ShowGamepadTextInput

Name	Type	Description
eInputMode	EGamepadTextInputMode	Selects the input mode to use, either Normal or Password (hidden text)
eLineInputMode	EGamepadTextInputLineMode	Controls whether to use single or multi line input.
pchDescription	const char *	Sets the description that should inform the user what the input dialog is for.
unCharMax	uint32	The maximum number of characters that the user can input.
pchExistingText	const 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

ShowFloatingGamepadTextInput

Name	Type	Description
eKeyboardMode	EFloatingGamepadTextInputMode	Selects the keyboard type to use
nTextFieldXPosition	int	X coordinate of text field which shouldn't be obscured by the floating keyboard
nTextFieldYPosition	int	Y coordinate of text field which shouldn't be obscured by the floating keyboard
nTextFieldWidth	int	width of text field which shouldn't be obscured by the floating keyboard
nTextFieldHeight	int	height of text field which shouldn't be obscured by the floating keyboard

Opens a floating keyboard over the game content and sends OS keyboard keys directly to the game.
The text field position is specified in pixels relative the origin of the game window and is used to position the floating keyboard in a way that doesn't cover the text field.

Returns: bool
true if the floating keyboard was shown, otherwise, false.

See Also: FloatingGamepadTextInputDismissed_t

StartVRDashboard

Asks Steam to create and render the OpenVR dashboard.

SetGameLauncherMode

Name	Type	Description
bLauncherMode	bool	Whether a launcher is active or not

In game launchers that don't have controller support you can call this to have Steam Input translate the controller input into mouse/kb to navigate the launcher

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.

Name	Type	Description
m_eCheckFileSignature	ECheckFileSignature	Contains 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.

Name	Type	Description
m_bSubmitted	bool	true if user entered & accepted text (Call GetEnteredGamepadTextInput to receive the text), false if input was canceled.
m_unSubmittedText	uint32	Contains the length in bytes if there was text submitted.

FloatingGamepadTextInputDismissed_t

Called when the floating keyboard invoked from ShowFloatingGamepadTextInput has been closed.

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.

Name	Type	Description
m_nMinutesBatteryLeft	uint8	The estimated amount of battery life left in minutes.

SteamAPICallCompleted_t

Called when a SteamAPICall_t has completed (or failed)

Name	Type	Description
m_hAsyncCall	SteamAPICall_t	The handle of the Steam API Call that completed.
m_iCallback	int	This is the k_iCallback constant which uniquely identifies the completed callback.
m_cubParam	uint32	The size in bytes of the completed callback.

AppResumingFromSuspend_t

Sent after the device returns from sleep/suspend mode.

This callback has no fields.

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

Name	Value	Description
k_ECheckFileSignatureInvalidSignature	0
k_ECheckFileSignatureValidSignature	1
k_ECheckFileSignatureFileNotFound	2
k_ECheckFileSignatureNoSignaturesFoundForThisApp	3
k_ECheckFileSignatureNoSignaturesFoundForThisFile	4

EGamepadTextInputLineMode

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

Name	Value	Description
k_EGamepadTextInputLineModeSingleLine	0
k_EGamepadTextInputLineModeMultipleLines	1

EGamepadTextInputMode

Input modes for the Big Picture gamepad text entry

Name	Value	Description
k_EGamepadTextInputModeNormal	0
k_EGamepadTextInputModePassword	1

EFloatingGamepadTextInputMode

Controls the mode for the floating keyboard

Name	Value	Description
k_EFloatingGamepadTextInputModeModeSingleLine	0	Enter dismisses the keyboard
k_EFloatingGamepadTextInputModeModeMultipleLines	1	User needs to explicitly dismiss the keyboard
k_EFloatingGamepadTextInputModeModeEmail	2	Keyboard is displayed in a special mode that makes it easier to enter emails
k_EFloatingGamepadTextInputModeModeNumeric	3	Numeric keypad is shown

ESteamAPICallFailure

Steam API call failure results returned by GetAPICallFailureReason.

Name	Value	Description
k_ESteamAPICallFailureNone	-1	No failure.
k_ESteamAPICallFailureSteamGone	0	The local Steam process has stopped responding, it may have been forcefully closed or is frozen.
k_ESteamAPICallFailureNetworkFailure	1	The 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_ESteamAPICallFailureInvalidHandle	2	The SteamAPICall_t handle passed in no longer exists.
k_ESteamAPICallFailureMismatchedCallback	3	GetAPICallResult was called with the wrong callback type for this API call.

Constants

These are constants which are defined for use with ISteamUtils.

Name	Type	Value	Description
STEAMUTILS_INTERFACE_VERSION	const char *	"SteamUtils009"