Functions for accessing and manipulating Steam user information.

This is also where the APIs for Steam Voice are exposed.

Member Functions

Member functions for ISteamUser are called through the global accessor function SteamUser().

AdvertiseGame

Name	Type	Description
steamIDGameServer	CSteamID	This should be k_steamIDNonSteamGS if you're setting the IP/Port, otherwise it should be k_steamIDNil if you're clearing this.
unIPServer	uint32	The IP of the game server in host order, i.e 127.0.0.1 == 0x7f000001.
usPortServer	uint16	The connection port of the game server, in host order.

Set the rich presence data for an unsecured game server that the user is playing on. This allows friends to be able to view the game info and join your game.

When you are using Steam authentication system this call is never required, the auth system automatically sets the appropriate rich presence.

BeginAuthSession

Name	Type	Description
pAuthTicket	const void *	The auth ticket to validate.
cbAuthTicket	int	The size in bytes of the auth ticket. This must be the pcbTicket size provided by the call that created this ticket.
steamID	CSteamID	The entity's Steam ID that sent this ticket.

Authenticate the ticket from the entity Steam ID to be sure it is valid and isn't reused. Note that identity is not confirmed until the callback ValidateAuthTicketResponse_t is received and the return value in that callback is checked for success.

The ticket is created on the entity with GetAuthSessionTicket or ISteamGameServer::GetAuthSessionTicket and then needs to be provided over the network for the other end to validate.

This registers for additional ValidateAuthTicketResponse_t callbacks if the entity goes offline or cancels the ticket. See EAuthSessionResponse for more information.

When the multiplayer session terminates you must call EndAuthSession.

Returns: EBeginAuthSessionResult
Triggers a ValidateAuthTicketResponse_t callback.



See Also: User Authentication and Ownership

BIsBehindNAT

Checks if the current user looks like they are behind a NAT device.

This is only valid if the user is connected to the Steam servers and may not catch all forms of NAT.

Returns: bool
true if the current user is behind a NAT, otherwise false.

BIsPhoneIdentifying

Checks whether the user's phone number is used to uniquely identify them.

Returns: bool
true if the current user's phone uniquely verifies their identity; otherwise, false.

BIsPhoneRequiringVerification

Checks whether the current user's phone number is awaiting (re)verification.

Returns: bool
true if current user's phone is requiring verification; otherwise, false.

BIsPhoneVerified

Checks whether the current user has verified their phone number.

See the Steam Guard Mobile Authenticator page on the customer facing Steam Support site for more information.

Returns: bool
true if the current user has phone verification enabled; otherwise, false.

BIsTwoFactorEnabled

Checks whether the current user has Steam Guard two factor authentication enabled on their account.

See the Steam Guard Mobile Authenticator page on the customer facing Steam Support site for more information.

Returns: bool
true if the current user has two factor authentication enabled; otherwise, false.

BLoggedOn

Checks if the current user's Steam client is connected to the Steam servers.

If it's not then no real-time services provided by the Steamworks API will be enabled. The Steam client will automatically be trying to recreate the connection as often as possible. When the connection is restored a SteamServersConnected_t callback will be posted.

You usually don't need to check for this yourself. All of the API calls that rely on this will check internally. Forcefully disabling stuff when the player loses access is usually not a very good experience for the player and you could be preventing them from accessing APIs that do not need a live connection to Steam.

Returns: bool
true if the Steam client current has a live connection to the Steam servers; otherwise, false if there is no active connection due to either a networking issue on the local machine, or the Steam server is down/busy.

BSetDurationControlOnlineState

Allows the game to specify the offline/online gameplay state for steam china duration control.

Parameters: EDurationControlOnlineState

Returns: bool
true if the online state was set successfully; otherwise, false.

Associated Functions:
GetDurationControl

CancelAuthTicket

Name	Type	Description
hAuthTicket	HAuthTicket	The active auth ticket to cancel.

Cancels an auth ticket received from GetAuthSessionTicket. This should be called when no longer playing with the specified entity.

See Also: User Authentication and Ownership

DecompressVoice

Name	Type	Description
pCompressed	const void *	The compressed data received from GetVoice.
cbCompressed	uint32	The size of the buffer passed into pCompressed.
pDestBuffer	void *	The buffer where the raw audio data will be returned. This can then be passed to your audio subsystems for playback.
cbDestBufferSize	uint32	The size of the buffer passed into pDestBuffer.
nBytesWritten	uint32 *	Returns the number of bytes written to pDestBuffer, or size of the buffer required to decompress the given data if cbDestBufferSize is not large enough (and k_EVoiceResultBufferTooSmall is returned).
nDesiredSampleRate	uint32	The sample rate that will be returned. This can be from 11025 to 48000, you should either use the rate that works best for your audio playback system, which likely takes the users audio hardware into account, or you can use GetVoiceOptimalSampleRate to get the native sample rate of the Steam voice decoder.

Decodes the compressed voice data returned by GetVoice.

The output data is raw single-channel 16-bit PCM audio. The decoder supports any sample rate from 11025 to 48000. See GetVoiceOptimalSampleRate for more information.

It is recommended that you start with a 20KiB buffer and then reallocate as necessary.

See Steam Voice for more information.

Returns: EVoiceResult
The internal sample rate of the Steam Voice decoder.

EndAuthSession

Name	Type	Description
steamID	CSteamID	The entity to end the active auth session with.

Ends an auth session that was started with BeginAuthSession. This should be called when no longer playing with the specified entity.

See Also: User Authentication and Ownership

GetAuthSessionTicket

Name	Type	Description
pTicket	void *	The buffer where the new auth ticket will be copied into if the call was successful.
cbMaxTicket	int	The size of the buffer allocated for pTicket. Typically a buffer size of 1024 will be sufficient. However, in certain cases (e.g., when an application has a large amount of available DLC), a larger buffer size may be required.
pcbTicket	uint32 *	Returns the length of the actual ticket.
pIdentityRemote	SteamNetworkingIdentity *	The identity of the remote system that will authenticate the ticket. If it is peer-to-peer then the user steam ID. If it is a game server, then the game server steam ID may be used if it was obtained from a trusted 3rd party, otherwise use the IP address. If it is a service, a string identifier of that service if one if provided.

Retrieve an authentication ticket to be sent to the entity who wishes to authenticate you.

After calling this you can send the ticket to the entity where they can then call BeginAuthSession/ISteamGameServer::BeginAuthSession to verify this entity's integrity.

Returns: HAuthTicket
Triggers a GetAuthSessionTicketResponse_t callback.
A handle to the auth ticket. When you're done interacting with the entity you must call CancelAuthTicket on the handle.

Returns k_HAuthTicketInvalid if the call fails.

See Also: User Authentication and Ownership

GetAuthTicketForWebApi

Name	Type	Description
*pchIdentity	const char *	The identity of the remote service that will authenticate the ticket. The service should provide a string identifier. Pass null if none was provided.

Retrieve an authentication ticket to be sent to the entity that wishes to authenticate you using the ISteamUserAuth/AuthenticateUserTicket Web API.
It is best practice to use an identity string for each service that will consume tickets.
Returns: HAuthTicket
Triggers a GetTicketForWebApiResponse_t callback.
A handle to the auth ticket. When you're done interacting with the entity you must call CancelAuthTicket on the handle.

Returns k_HAuthTicketInvalid if the call fails.

See Also: User Authentication and Ownership

GetAvailableVoice

Name	Type	Description
pcbCompressed	uint32 *	Returns the size of the available voice data in bytes.
pcbUncompressed_Deprecated	uint32 *	Deprecated.
nUncompressedVoiceDesiredSampleRate_Deprecated	uint32	Deprecated.

Checks to see if there is captured audio data available from GetVoice, and gets the size of the data.

Most applications will only use compressed data and should ignore the other parameters, which exist primarily for backwards compatibility. See GetVoice for further explanation of "uncompressed" data.

See Steam Voice for more information.

Returns: EVoiceResult

GetDurationControl

Retrieves anti indulgence / duration control for current user / game combination.


Returns: SteamAPICall_t to be used with a DurationControl_t call result.
Returns k_uAPICallInvalid if no connection to the Steam servers could be made.

Associated Functions:
BSetDurationControlOnlineState

GetEncryptedAppTicket

Name	Type	Description
pTicket	void *	The encrypted app ticket is copied into this buffer.
cbMaxTicket	int	The total size of the pTicket buffer in bytes.
pcbTicket	uint32 *	Returns the number of bytes copied into pTicket.

Retrieve an encrypted ticket.

This should be called after requesting an encrypted app ticket with RequestEncryptedAppTicket and receiving the EncryptedAppTicketResponse_t call result.

You should then pass this encrypted ticket to your secure servers to be decrypted using your secret key using SteamEncryptedAppTicket::BDecryptTicket.

NOTE: If you call this without calling RequestEncryptedAppTicket, the call may succeed but you will likely get a stale ticket.

Returns: bool
true if the call successfully returned an app ticket into pTicket.
false under the following conditions:

• pcbTicket is NULL
  
• pTicket is NULL
  
• pTicket is too small to hold this ticket.
  
• There was no ticket available. (Did you wait for EncryptedAppTicketResponse_t?)

GetGameBadgeLevel

Name	Type	Description
nSeries	int	If you only have one set of cards, the series will be 1.
bFoil	bool	Check if they have received the foil badge.

Gets the level of the users Steam badge for your game.

The user can have two different badges for a series; the regular badge (max level 5) and the foil badge (max level 1).

Returns: int
The level of the badge, 0 if they don't have it.

GetHSteamUser

Gets Steam user handle that this interface represents.

This is only used internally by the API, and by a few select interfaces that support multi-user.

Returns: HSteamUser

GetPlayerSteamLevel

Gets the Steam level of the user, as shown on their Steam community profile.

Returns: int
The level of the current user.

GetSteamID

Gets the Steam ID of the account currently logged into the Steam client. This is commonly called the 'current user', or 'local user'.

A Steam ID is a unique identifier for a Steam accounts, Steam groups, Lobbies and Chat rooms, and used to differentiate users in all parts of the Steamworks API.

Returns: CSteamID


Example:

GetUserDataFolder

Name	Type	Description
pchBuffer	char *
cubBuffer	int

Deprecated - You should use the Steam Cloud API from ISteamRemoteStorage instead.

Returns: bool

GetVoice

Name	Type	Description
bWantCompressed	bool	This should always be true.
pDestBuffer	void *	The buffer where the audio data will be copied into.
cbDestBufferSize	uint32	The size of the buffer allocated for pDestBuffer.
nBytesWritten	uint32 *	Returns the number of bytes written into pDestBuffer. This should always be the size returned by ISteamUser::GetAvailableVoice.
bWantUncompressed_Deprecated	bool	Deprecated.
pUncompressedDestBuffer_Deprecated	void *	Deprecated.
cbUncompressedDestBufferSize_Deprecated	uint32	Deprecated.
nUncompressBytesWritten_Deprecated	uint32 *	Deprecated.
nUncompressedVoiceDesiredSampleRate_Deprecated	uint32	Deprecated.

Read captured audio data from the microphone buffer.

The compressed data can be transmitted by your application and decoded back into raw audio data using DecompressVoice on the other side. The compressed data provided is in an arbitrary format and is not meant to be played directly.

This should be called once per frame, and at worst no more than four times a second to keep the microphone input delay as low as possible. Calling this any less may result in gaps in the returned stream.

It is recommended that you pass in an 8 kilobytes or larger destination buffer for compressed audio. Static buffers are recommended for performance reasons. However, if you would like to allocate precisely the right amount of space for a buffer before each call you may use GetAvailableVoice to find out how much data is available to be read.

NOTE: "Uncompressed" audio is a deprecated feature and should not be used by most applications. It is raw single-channel 16-bit PCM wave data which may have been run through preprocessing filters and/or had silence removed, so the uncompressed audio could have a shorter duration than you expect. There may be no data at all during long periods of silence. Also, fetching uncompressed audio will cause GetVoice to discard any leftover compressed audio, so you must fetch both types at once. Finally, GetAvailableVoice is not precisely accurate when the uncompressed size is requested. So if you really need to use uncompressed audio, you should call GetVoice frequently with two very large (20KiB+) output buffers instead of trying to allocate perfectly-sized buffers. But most applications should ignore all of these details and simply leave the "uncompressed" parameters as NULL/0.

See Steam Voice for more information.

Returns: EVoiceResult

GetVoiceOptimalSampleRate

Gets the native sample rate of the Steam voice decoder.

Using this sample rate for DecompressVoice will perform the least CPU processing. However, the final audio quality will depend on how well the audio device (and/or your application's audio output SDK) deals with lower sample rates. You may find that you get the best audio output quality when you ignore this function and use the native sample rate of your audio output device, which is usually 48000 or 44100.

See Steam Voice for more information.

Returns: uint32

InitiateGameConnection

Name	Type	Description
pAuthBlob	void *	A pointer to empty memory that will be filled in with the authentication token.
cbMaxAuthBlob	int	The number of bytes of allocated memory in pBlob. Should be at least 2048 bytes.
steamIDGameServer	CSteamID	The Steam ID of the game server, received from the game server by the client.
unIPServer	uint32	The IP address of the game server in host order, i.e 127.0.0.1 == 0x7f000001.
usPortServer	uint16	The connection port of the game server, in host order.
bSecure	bool	Whether or not the client thinks that the game server is reporting itself as secure (i.e. VAC is running.)

This starts the state machine for authenticating the game client with the game server.

It is the client portion of a three-way handshake between the client, the game server, and the steam servers.

NOTE: When you're done with the connection you must call TerminateGameConnection.

NOTE: This is part of the old user authentication API and should not be mixed with the new API.

Returns: int
The number of bytes written to pBlob.

Returns 0 indicating failure, signifying that the pAuthBlob buffer passed in was too small, and the call has failed.

The contents of pAuthBlob should then be sent to the game server, for it to use to complete the authentication process.

RequestEncryptedAppTicket

Name	Type	Description
pDataToInclude	void *	The data which will be encrypted into the ticket.
cbDataToInclude	int	The total size in bytes of pDataToInclude.

Requests an application ticket encrypted with the secret "encrypted app ticket key".

The encryption key can be obtained from the Encrypted App Ticket Key page on the App Admin for your app.

There can only be one EncryptedAppTicketResponse_t pending, and this call is subject to a 60 second rate limit.

After receiving the response you should call GetEncryptedAppTicket to get the ticket data, and then you need to send it to a secure server to be decrypted with the SteamEncryptedAppTicket functions.

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


Example:

RequestStoreAuthURL

Name	Type	Description
pchRedirectURL	const char *

Requests a URL which authenticates an in-game browser for store check-out, and then redirects to the specified URL.

As long as the in-game browser accepts and handles session cookies, Steam microtransaction checkout pages will automatically recognize the user instead of presenting a login page.

NOTE: The URL has a very short lifetime to prevent history-snooping attacks, so you should only call this API when you are about to launch the browser, or else immediately navigate to the result URL using a hidden browser window.

NOTE: The resulting authorization cookie has an expiration time of one day, so it would be a good idea to request and visit a new auth URL every 12 hours.

Returns: SteamAPICall_t to be used with a StoreAuthURLResponse_t call result.
Returns k_uAPICallInvalid if no connection to the Steam servers could be made.

StartVoiceRecording

Starts voice recording.

Once started, use GetAvailableVoice and GetVoice to get the data, and then call StopVoiceRecording when the user has released their push-to-talk hotkey or the game session has completed.

See Steam Voice for more information.

StopVoiceRecording

Stops voice recording.

Because people often release push-to-talk keys early, the system will keep recording for a little bit after this function is called. As such, GetVoice should continue to be called until it returns k_EVoiceResultNotRecording, only then will voice recording be stopped.

TerminateGameConnection

Name	Type	Description
unIPServer	uint32
usPortServer	uint16

Notify the game server that we are disconnecting.

This needs to occur when the game client leaves the specified game server, needs to match with the InitiateGameConnection call.

NOTE: This is part of the old user authentication API and should not be mixed with the new API.

TrackAppUsageEvent

Name	Type	Description
gameID	CGameID
eAppUsageEvent	int
pchExtraInfo	const char *

Deprecated - Only used by only a few games to track usage events before Stats and Achievements was introduced.

UserHasLicenseForApp

Name	Type	Description
steamID	CSteamID	The Steam ID of the user that sent the auth ticket.
appID	AppId_t	The DLC App ID to check if the user owns it.

Checks if the user owns a specific piece of Downloadable Content (DLC).

This can only be called after sending the users auth ticket to ISteamGameServer::BeginAuthSession

Returns: EUserHasLicenseForAppResult


See Also: User Authentication and Ownership

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 ISteamUser.

ClientGameServerDeny_t

Sent by the Steam server to the client telling it to disconnect from the specified game server, which it may be in the process of or already connected to.
The game client should immediately disconnect upon receiving this message.
This can usually occur if the user doesn't have rights to play on the game server.

Name	Type	Description
m_uAppID	uint32	The App ID this call is for. Verify that it's the same as the current App ID with ISteamUtils::GetAppID.
m_unGameServerIP	uint32	The IP of the game server that is telling us to disconnect, in host order, i.e 127.0.0.1 == 0x7f000001.
m_usGameServerPort	uint16	The port of the game server that is telling us to disconnect, in host order.
m_bSecure	uint16	Is the game server VAC secure (true) or not (false)?
m_uReason	uint32

DurationControl_t

Sent for games with enabled anti indulgence / duration control, for enabled users. Lets the game know whether the feature applies to the user, whether the user needs to exit the game soon, and the remaining daily playtime for the user.

This callback is fired asynchronously in response to timers triggering. It is also fired in response to calls to GetDurationControl().

Name	Type	Description
m_eResult	EResult	result of call (always k_EResultOK for asynchronous timer-based notifications)
m_appid	AppId_t	appid generating playtime
m_bApplicable	bool	is duration control applicable to user + game combination
m_csecsLast5h	int32	playtime in trailing 5 hour window plus current session, in seconds
m_progress	EDurationControlProgress	Description of whether the game should exit
m_notification	EDurationControlNotification	notification to show, if any (always k_EDurationControlNotification_None for API calls)

Associated Functions: GetDurationControl

EncryptedAppTicketResponse_t

Called when an encrypted application ticket has been received.

Name	Type	Description
m_eResult	EResult	Was the call successful? Possible results: k_EResultOK - Success! k_EResultNoConnection - A connection to Steam could not be established. k_EResultDuplicateRequest - There is already a pending request. k_EResultLimitExceeded - This call is subject to a 60 second rate limit, and you have exceeded that.

Associated Functions: RequestEncryptedAppTicket

GameWebCallback_t

Sent to your game in response to a steam://gamewebcallback/ command from a user clicking a link in the Steam overlay browser.
You can use this to add support for external site signups where you want to pop back into the browser after some web page signup sequence, and optionally get back some detail about that.

Name	Type	Description
m_szURL	char［256］	The complete url that the user clicked on.

GetAuthSessionTicketResponse_t

Result when creating an auth session ticket.

Name	Type	Description
m_hAuthTicket	HAuthTicket	The handle to the ticket that was created.
m_eResult	EResult	The result of the operation.

Associated Functions: GetAuthSessionTicket

GetTicketForWebApiResponse_t

Result when creating an webapi ticket from GetAuthTicketForWebApi.

Name	Type	Description
m_hAuthTicket	HAuthTicket	The handle to the ticket that was created.
m_eResult	EResult	The result of the operation.
m_cubTicket	int	The length of the ticket that was created.
m_rgubTicket	uint8[2560]	The ticket that was created.

Associated Functions: GetAuthTicketForWebApi

IPCFailure_t

Called when the callback system for this client is in an error state (and has flushed pending callbacks)
When getting this message the client should disconnect from Steam, reset any stored Steam state and reconnect.
This usually occurs in the rare event the Steam client has some kind of fatal error.

Name	Type	Description
m_eFailureType	uint8	This is a EFailureType.

LicensesUpdated_t

Called whenever the users licenses (owned packages) changes.

This callback has no fields.

MicroTxnAuthorizationResponse_t

Called when a user has responded to a microtransaction authorization request.

Name	Type	Description
m_unAppID	uint32	App ID for this microtransaction
m_ulOrderID	uint64	Order ID provided for the microtransaction.
m_bAuthorized	uint8	Did the user authorize the transaction (1) or not (0)?

SteamServerConnectFailure_t

Called when a connection attempt has failed.
This will occur periodically if the Steam client is not connected, and has failed when retrying to establish a connection.

Name	Type	Description
m_eResult	EResult	The reason why the connection failed.
m_bStillRetrying	bool	Is the Steam client still trying to connect to the server?

SteamServersConnected_t

Called when a connections to the Steam back-end has been established.
This means the Steam client now has a working connection to the Steam servers. Usually this will have occurred before the game has launched, and should only be seen if the user has dropped connection due to a networking issue or a Steam server update.

This callback has no fields.

SteamServersDisconnected_t

Called if the client has lost connection to the Steam servers.
Real-time services will be disabled until a matching SteamServersConnected_t has been posted.

Name	Type	Description
m_eResult	EResult	The reason we were disconnected from Steam.

StoreAuthURLResponse_t

Response when we have recieved the authentication URL after a call to RequestStoreAuthURL.

Name	Type	Description
m_szURL	char［512］	The authentication URL.

Associated Functions: RequestStoreAuthURL

ValidateAuthTicketResponse_t

Called when an auth ticket has been validated.

Name	Type	Description
m_SteamID	CSteamID	The Steam ID of the entity that provided the auth ticket.
m_eAuthSessionResponse	EAuthSessionResponse	The result of the validation.
m_OwnerSteamID	CSteamID	The Steam ID that owns the game, this will be different from m_SteamID if the game is being accessed via Steam Family Sharing.

Associated Functions: BeginAuthSession

Structs

These are structs which functions in ISteamUser may return and/or interact with.

CallbackMsg_t

The structure that contains client callback data. This is only used internally inside SteamAPI_RunCallbacks.

Name	Type	Description
m_hSteamUser	HSteamUser	The user this callback is sent to.
m_iCallback	int	The unique ID of the callback.
m_pubParam	uint8 *	The pointer to the callback data.
m_cubParam	int	The size of [param]m_pubParam[/param].

Enums

These are enums which are defined for use with ISteamUser.

EFailureType

Specifies what type of failure happened in IPCFailure_t.

Name	Value	Description
k_EFailureFlushedCallbackQueue	0
k_EFailurePipeFail	1

EDurationControlProgress

Describes playtime restrictions that apply for games with duration control / anti-indulgence enabled for minor Steam China users.

Name	Value	Description
k_EDurationControlProgress_Full	0	Normal play
k_EDurationControlProgress_Half	1	(This value is deprecated)
k_EDurationControlProgress_None	2	User's playtime has run out. Steam will terminate the game soon

Associated Functions:
GetDurationControl
BSetDurationControlOnlineState

EDurationControlNotification

Describes which notification timer has expired, for steam china duration control feature. Some of these notifications are deprecated and are no longer sent.

Name	Value	Description
k_EDurationControlNotification_None	0	Callback is just informing you about progress, no notification to show
k_EDurationControlNotification_1Hour	1	player has been playing for an hour - game can show something at this time if desired
k_EDurationControlNotification_3Hours	2	(deprecated)
k_EDurationControlNotification_HalfProgress	3	(deprecated)
k_EDurationControlNotification_ExitSoon_3h	4	player has been playing for the allowed time and should exit the game
k_EDurationControlNotification_ExitSoon_5h	4	player has been playing for the allowed time and should exit the game
k_EDurationControlNotification_ExitSoon_Night	4	player has been playing until the locally allowed time of day (10PM) and should exit the game

Associated Functions:
GetDurationControl
BSetDurationControlOnlineState

EDurationControlOnlineState

Describes the online/offline play state of a game. Currently this is only used to support the game being able to prevent steam from exiting the game automatically when the user's playtime is consumed. If the game calls BSetDurationControlOnlineState(k_EDurationControlOnlineState_OnlineHighPri) then Steam will not force exit the game - in this case it is up to the game to do so! Steam will continue to send DurationControl_t notifications to the game. If the game later calls BSetDurationControlOnlineState to remove the OnlineHighPri state, then Steam will force exit the game soon thereafter.

Name	Value	Description
k_EDurationControlOnlineState_Offline	1	Offline play
k_EDurationControlOnlineState_Online	2	Online play
k_EDurationControlOnlineState_OnlineHighPri	3	Online play - game requests that steam not force exit the game

Associated Functions:
GetDurationControl
BSetDurationControlOnlineState

Constants

These are constants which are defined for use with ISteamUser.

Name	Type	Value	Description
STEAMUSER_INTERFACE_VERSION	const char *	"SteamUser019"