//====== Copyright (c) 1996-2008, Valve Corporation, All rights reserved. //======= // // Purpose: interface to user account information in Steam // //============================================================================= #ifndef ISTEAMUSER_H #define ISTEAMUSER_H #ifdef _WIN32 #pragma once #endif #include "isteamclient.h" // structure that contains client callback data // see callbacks documentation for more details #if defined(VALVE_CALLBACK_PACK_SMALL) #pragma pack(push, 4) #elif defined(VALVE_CALLBACK_PACK_LARGE) #pragma pack(push, 8) #else #error isteamclient.h must be included #endif struct CallbackMsg_t { HSteamUser m_hSteamUser; int m_iCallback; uint8 *m_pubParam; int m_cubParam; }; #pragma pack(pop) // reference to a steam call, to filter results by typedef int32 HSteamCall; //----------------------------------------------------------------------------- // Purpose: Functions for accessing and manipulating a steam account // associated with one client instance //----------------------------------------------------------------------------- class ISteamUser { public: // returns the HSteamUser this interface represents // this is only used internally by the API, and by a few select interfaces // that support multi-user virtual HSteamUser GetHSteamUser() = 0; // returns true if the Steam client current has a live connection to the // Steam servers. If false, it means there is no active connection due to // either a networking issue on the local machine, or the Steam server is // down/busy. The Steam client will automatically be trying to recreate the // connection as often as possible. virtual bool BLoggedOn() = 0; // returns the CSteamID of the account currently logged into the Steam // client a CSteamID is a unique identifier for an account, and used to // differentiate users in all parts of the Steamworks API virtual CSteamID GetSteamID() = 0; // Multiplayer Authentication functions // InitiateGameConnection() 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 // // Parameters: // void *pAuthBlob - a pointer to empty memory that will be filled in with // the authentication token. int cbMaxAuthBlob - the number of bytes of // allocated memory in pBlob. Should be at least 2048 bytes. CSteamID // steamIDGameServer - the steamID of the game server, received from the // game server by the client CGameID gameID - the ID of the current game. // For games without mods, this is just CGameID( ) uint32 // unIPServer, uint16 usPortServer - the IP address of the game server bool // bSecure - whether or not the client thinks that the game server is // reporting itself as secure (i.e. VAC is running) // // return value - returns the number of bytes written to pBlob. If the // return is 0, then the buffer passed in was too small, and the call has // failed The contents of pBlob should then be sent to the game server, for // it to use to complete the authentication process. virtual int InitiateGameConnection(void *pAuthBlob, int cbMaxAuthBlob, CSteamID steamIDGameServer, uint32 unIPServer, uint16 usPortServer, bool bSecure) = 0; // notify of disconnect // needs to occur when the game client leaves the specified game server, // needs to match with the InitiateGameConnection() call virtual void TerminateGameConnection(uint32 unIPServer, uint16 usPortServer) = 0; // Legacy functions // used by only a few games to track usage events virtual void TrackAppUsageEvent(CGameID gameID, int eAppUsageEvent, const char *pchExtraInfo = "") = 0; // get the local storage folder for current Steam account to write // application data, e.g. save games, configs etc. this will usually be // something like "C:\Progam Files\Steam\userdata\\\local" virtual bool GetUserDataFolder(char *pchBuffer, int cubBuffer) = 0; // Starts voice recording. Once started, use GetVoice() to get the data virtual void StartVoiceRecording() = 0; // 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. GetVoice() should continue to be called until it // returns k_eVoiceResultNotRecording virtual void StopVoiceRecording() = 0; // Determine the amount of captured audio data that is available in bytes. // This provides both the compressed and uncompressed data. Please note that // the uncompressed data is not the raw feed from the microphone: data may // only be available if audible levels of speech are detected. // nUncompressedVoiceDesiredSampleRate is necessary to know the number of // bytes to return in pcbUncompressed - can be set to 0 if you don't need // uncompressed (the usual case) If you're upgrading from an older // Steamworks API, you'll want to pass in 11025 to // nUncompressedVoiceDesiredSampleRate virtual EVoiceResult GetAvailableVoice( uint32 *pcbCompressed, uint32 *pcbUncompressed, uint32 nUncompressedVoiceDesiredSampleRate) = 0; // Gets the latest voice data from the microphone. Compressed data is an // arbitrary format, and is meant to be handed back to DecompressVoice() for // playback later as a binary blob. Uncompressed data is 16-bit, signed // integer, 11025Hz PCM format. Please note that the uncompressed data is // not the raw feed from the microphone: data may only be available if // audible levels of speech are detected, and may have passed through // denoising filters, etc. This function should be called as often as // possible once recording has started; once per frame at least. // nBytesWritten is set to the number of bytes written to pDestBuffer. // nUncompressedBytesWritten is set to the number of bytes written to // pUncompressedDestBuffer. You must grab both compressed and uncompressed // here at the same time, if you want both. Matching data that is not read // during this call will be thrown away. GetAvailableVoice() can be used to // determine how much data is actually available. If you're upgrading from // an older Steamworks API, you'll want to pass in 11025 to // nUncompressedVoiceDesiredSampleRate virtual EVoiceResult GetVoice( bool bWantCompressed, void *pDestBuffer, uint32 cbDestBufferSize, uint32 *nBytesWritten, bool bWantUncompressed, void *pUncompressedDestBuffer, uint32 cbUncompressedDestBufferSize, uint32 *nUncompressBytesWritten, uint32 nUncompressedVoiceDesiredSampleRate) = 0; // Decompresses a chunk of compressed data produced by GetVoice(). // nBytesWritten is set to the number of bytes written to pDestBuffer unless // the return value is k_EVoiceResultBufferTooSmall. In that case, // nBytesWritten is set to the size of the buffer required to decompress the // given data. The suggested buffer size for the destination buffer is 22 // kilobytes. The output format of the data is 16-bit signed at the // requested samples per second. If you're upgrading from an older // Steamworks API, you'll want to pass in 11025 to nDesiredSampleRate virtual EVoiceResult DecompressVoice(const void *pCompressed, uint32 cbCompressed, void *pDestBuffer, uint32 cbDestBufferSize, uint32 *nBytesWritten, uint32 nDesiredSampleRate) = 0; // This returns the frequency of the voice data as it's stored internally; // calling DecompressVoice() with this size will yield the best results virtual uint32 GetVoiceOptimalSampleRate() = 0; // Retrieve ticket to be sent to the entity who wishes to authenticate you. // pcbTicket retrieves the length of the actual ticket. virtual HAuthTicket GetAuthSessionTicket(void *pTicket, int cbMaxTicket, uint32 *pcbTicket) = 0; // Authenticate ticket from entity steamID to be sure it is valid and isnt // reused Registers for callbacks if the entity goes offline or cancels the // ticket ( see ValidateAuthTicketResponse_t callback and // EAuthSessionResponse ) virtual EBeginAuthSessionResult BeginAuthSession(const void *pAuthTicket, int cbAuthTicket, CSteamID steamID) = 0; // Stop tracking started by BeginAuthSession - called when no longer playing // game with this entity virtual void EndAuthSession(CSteamID steamID) = 0; // Cancel auth ticket from GetAuthSessionTicket, called when no longer // playing game with the entity you gave the ticket to virtual void CancelAuthTicket(HAuthTicket hAuthTicket) = 0; // After receiving a user's authentication data, and passing it to // BeginAuthSession, use this function to determine if the user owns // downloadable content specified by the provided AppID. virtual EUserHasLicenseForAppResult UserHasLicenseForApp(CSteamID steamID, AppId_t appID) = 0; // returns true if this users looks like they are behind a NAT device. Only // valid once the user has connected to steam (i.e a SteamServersConnected_t // has been issued) and may not catch all forms of NAT. virtual bool BIsBehindNAT() = 0; // set data to be replicated to friends so that they can join your game // CSteamID steamIDGameServer - the steamID of the game server, received // from the game server by the client uint32 unIPServer, uint16 usPortServer // - the IP address of the game server virtual void AdvertiseGame(CSteamID steamIDGameServer, uint32 unIPServer, uint16 usPortServer) = 0; // Requests a ticket encrypted with an app specific shared key // pDataToInclude, cbDataToInclude will be encrypted into the ticket // ( This is asynchronous, you must wait for the ticket to be completed by // the server ) virtual SteamAPICall_t RequestEncryptedAppTicket(void *pDataToInclude, int cbDataToInclude) = 0; // retrieve a finished ticket virtual bool GetEncryptedAppTicket(void *pTicket, int cbMaxTicket, uint32 *pcbTicket) = 0; // Trading Card badges data access // if you only have one set of cards, the series will be 1 // the user has can have two different badges for a series; the regular (max // level 5) and the foil (max level 1) virtual int GetGameBadgeLevel(int nSeries, bool bFoil) = 0; // gets the Steam Level of the user, as shown on their profile virtual int GetPlayerSteamLevel() = 0; // 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. The result of this API call will be a // StoreAuthURLResponse_t callback. 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 2: 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. virtual SteamAPICall_t RequestStoreAuthURL(const char *pchRedirectURL) = 0; #ifdef _PS3 // Initiates PS3 Logon request using just PSN ticket. // // PARAMS: bInteractive - If set tells Steam to go ahead and show the PS3 // NetStart dialog if needed to prompt the user for network setup/PSN logon // before initiating the Steam side of the logon. // // Listen for SteamServersConnected_t or SteamServerConnectFailure_t for // status. SteamServerConnectFailure_t may return with EResult // k_EResultExternalAccountUnlinked if the PSN account is unknown to Steam. // You should then call LogOnAndLinkSteamAccountToPSN() after prompting the // user for credentials to establish a link. Future calls to LogOn() after // the one time link call should succeed as long as the user is connected to // PSN. virtual void LogOn(bool bInteractive) = 0; // Initiates a request to logon with a specific steam username/password and // create a PSN account link at the same time. Should call this only if // LogOn() has failed and indicated the PSN account is unlinked. // // PARAMS: bInteractive - If set tells Steam to go ahead and show the PS3 // NetStart dialog if needed to prompt the user for network setup/PSN logon // before initiating the Steam side of the logon. pchUserName should be the // users Steam username, and pchPassword should be the users Steam password. // // Listen for SteamServersConnected_t or SteamServerConnectFailure_t for // status. SteamServerConnectFailure_t may return with EResult // k_EResultOtherAccountAlreadyLinked if already linked to another account. virtual void LogOnAndLinkSteamAccountToPSN(bool bInteractive, const char *pchUserName, const char *pchPassword) = 0; // Final logon option for PS3, this logs into an existing account if already // linked, but if not already linked creates a new account using the info in // the PSN ticket to generate a unique account name. The new account is // then linked to the PSN ticket. This is the faster option for new users // who don't have an existing Steam account to get into multiplayer. // // PARAMS: bInteractive - If set tells Steam to go ahead and show the PS3 // NetStart dialog if needed to prompt the user for network setup/PSN logon // before initiating the Steam side of the logon. virtual void LogOnAndCreateNewSteamAccountIfNeeded(bool bInteractive) = 0; // Returns a special SteamID that represents the user's PSN information. Can // be used to query the user's PSN avatar, online name, etc. through the // standard Steamworks interfaces. virtual CSteamID GetConsoleSteamID() = 0; #endif }; #define STEAMUSER_INTERFACE_VERSION "SteamUser018" // callbacks #if defined(VALVE_CALLBACK_PACK_SMALL) #pragma pack(push, 4) #elif defined(VALVE_CALLBACK_PACK_LARGE) #pragma pack(push, 8) #else #error isteamclient.h must be included #endif //----------------------------------------------------------------------------- // Purpose: 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 //----------------------------------------------------------------------------- struct SteamServersConnected_t { enum { k_iCallback = k_iSteamUserCallbacks + 1 }; }; //----------------------------------------------------------------------------- // Purpose: called when a connection attempt has failed // this will occur periodically if the Steam client is not //connected, and has failed in it's retry to establish a connection //----------------------------------------------------------------------------- struct SteamServerConnectFailure_t { enum { k_iCallback = k_iSteamUserCallbacks + 2 }; EResult m_eResult; }; //----------------------------------------------------------------------------- // Purpose: 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 //----------------------------------------------------------------------------- struct SteamServersDisconnected_t { enum { k_iCallback = k_iSteamUserCallbacks + 3 }; EResult m_eResult; }; //----------------------------------------------------------------------------- // Purpose: 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. //----------------------------------------------------------------------------- struct ClientGameServerDeny_t { enum { k_iCallback = k_iSteamUserCallbacks + 13 }; uint32 m_uAppID; uint32 m_unGameServerIP; uint16 m_usGameServerPort; uint16 m_bSecure; uint32 m_uReason; }; //----------------------------------------------------------------------------- // Purpose: 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. //----------------------------------------------------------------------------- struct IPCFailure_t { enum { k_iCallback = k_iSteamUserCallbacks + 17 }; enum EFailureType { k_EFailureFlushedCallbackQueue, k_EFailurePipeFail, }; uint8 m_eFailureType; }; //----------------------------------------------------------------------------- // Purpose: Signaled whenever licenses change //----------------------------------------------------------------------------- struct LicensesUpdated_t { enum { k_iCallback = k_iSteamUserCallbacks + 25 }; }; //----------------------------------------------------------------------------- // callback for BeginAuthSession //----------------------------------------------------------------------------- struct ValidateAuthTicketResponse_t { enum { k_iCallback = k_iSteamUserCallbacks + 43 }; CSteamID m_SteamID; EAuthSessionResponse m_eAuthSessionResponse; CSteamID m_OwnerSteamID; // different from m_SteamID if borrowed }; //----------------------------------------------------------------------------- // Purpose: called when a user has responded to a microtransaction authorization // request //----------------------------------------------------------------------------- struct MicroTxnAuthorizationResponse_t { enum { k_iCallback = k_iSteamUserCallbacks + 52 }; uint32 m_unAppID; // AppID for this microtransaction uint64 m_ulOrderID; // OrderID provided for the microtransaction uint8 m_bAuthorized; // if user authorized transaction }; //----------------------------------------------------------------------------- // Purpose: Result from RequestEncryptedAppTicket //----------------------------------------------------------------------------- struct EncryptedAppTicketResponse_t { enum { k_iCallback = k_iSteamUserCallbacks + 54 }; EResult m_eResult; }; //----------------------------------------------------------------------------- // callback for GetAuthSessionTicket //----------------------------------------------------------------------------- struct GetAuthSessionTicketResponse_t { enum { k_iCallback = k_iSteamUserCallbacks + 63 }; HAuthTicket m_hAuthTicket; EResult m_eResult; }; //----------------------------------------------------------------------------- // Purpose: sent to your game in response to a steam://gamewebcallback/ command //----------------------------------------------------------------------------- struct GameWebCallback_t { enum { k_iCallback = k_iSteamUserCallbacks + 64 }; char m_szURL[256]; }; //----------------------------------------------------------------------------- // Purpose: sent to your game in response to ISteamUser::RequestStoreAuthURL //----------------------------------------------------------------------------- struct StoreAuthURLResponse_t { enum { k_iCallback = k_iSteamUserCallbacks + 65 }; char m_szURL[512]; }; #pragma pack(pop) #endif // ISTEAMUSER_H