top of page

Market Research Group

Public·16 members

Steamworks API Overview (Steamworks Documentation)[^1^]


Steam API Unregister Call Result: What It Is and How It Affects Your Game




If you are developing a game using Steamworks API, you may have encountered the term Steam API Unregister Call Result. But what does it mean and why do you need it? In this article, we will explain what Steam API Unregister Call Result is, how it works, how it affects your game, and how to use it correctly. By the end of this article, you will have a better understanding of this important feature of Steamworks API and how to leverage it for your game's success.




Steam Api Unregister Call Result



How Steamworks API Works




Steamworks API is a set of interfaces, functions, callbacks, and events that allow your game to access various Steam features and services, such as achievements, leaderboards, matchmaking, networking, user authentication, cloud storage, and more. Steamworks API is available for multiple platforms, such as Windows, Mac, Linux, iOS, Android, and Web. Steamworks API is designed to be easy to use and integrate with your game engine and code base.


To use Steamworks API, you need to create a Steamworks account and register your game as a Steam product. You also need to download the Steamworks SDK and link it with your game project. The Steamworks SDK contains the libraries, headers, documentation, and samples that you need to work with Steamworks API. You can choose from different languages and frameworks to work with Steamworks API, such as C++, C#, Unity, Unreal Engine, and more.


Once you have set up your game project with Steamworks SDK, you can start calling Steamworks API functions from your game code. These functions allow you to interact with various Steam subsystems and services. For example, you can call SteamUserStats()->SetAchievement("ACH_WIN_ONE_GAME"); to unlock an achievement for the current user, or call SteamMatchmaking()->CreateLobby(k_ELobbyTypePublic, 4); to create a public lobby for up to 4 players.


Some of these functions are asynchronous, meaning that they do not return a value immediately, but instead initiate a request to the Steam servers and return a handle of type SteamAPICall_t. This handle represents the pending request and can be used to check its status or cancel it. For example, the function SteamUserStats()->RequestCurrentStats(); is asynchronous and returns a SteamAPICall_t handle. This function requests the current user's stats from the Steam servers and returns immediately without waiting for the response.


To get the result of an asynchronous function call, you need to use a callback object that inherits from CCallbackBase. This object defines a function that will be called when the result is ready. You also need to use the macro CALL_RESULT() to associate the callback object with the SteamAPICall_t handle. For example, you can define a callback object like this:



class CRequestStatsCallback : public CCallbackBase public: CRequestStatsCallback() m_iCallback = UserStatsReceived_t::k_iCallback; void Run( void *pvParam ) UserStatsReceived_t *pParam = (UserStatsReceived_t *)pvParam; // Handle the result here ;


And then use it like this:



CRequestStatsCallback g_RequestStatsCallback; CALL_RESULT( g_RequestStatsCallback ); SteamAPICall_t hSteamAPICall = SteamUserStats()->RequestCurrentStats(); g_RequestStatsCallback.SetGameserverFlag(); // If this is called from a game server g_RequestStatsCallback.Set( hSteamAPICall );


This way, when the result of RequestCurrentStats() is ready, the function CRequestStatsCallback::Run() will be called with a parameter of type UserStatsReceived_t, which contains the result data.


What Is Steam API Unregister Call Result




The Definition of Steam API Unregister Call Result




Steam API Unregister Call Result is a function that allows you to unregister a callback object from a SteamAPICall_t handle. The function has the following signature:



void SteamAPI_UnregisterCallResult( class CCallbackBase *pCallback, SteamAPICall_t hAPICall );


The function takes two parameters: a pointer to a callback object that inherits from CCallbackBase, and a SteamAPICall_t handle that represents an asynchronous function call. The function removes the association between the callback object and the handle, so that the callback object will not be called when the result is ready.


The Purpose of Steam API Unregister Call Result




The purpose of Steam API Unregister Call Result is to avoid memory leaks and performance issues when using asynchronous function calls. When you use a callback object with a CALL_RESULT() macro, you are creating a dynamic allocation of memory for the callback object. This memory will not be freed until the result is ready and the callback object is called. However, sometimes you may not need or want to wait for the result, or you may want to cancel the request. In these cases, you should use Steam API Unregister Call Result to free the memory and avoid unnecessary callbacks.


For example, suppose you have a function that requests a leaderboard entry for a user, and you use a callback object to handle the result. However, before the result is ready, the user quits the game or switches to another screen. In this case, you don't need the result anymore, and you don't want the callback object to be called. Therefore, you should use Steam API Unregister Call Result to unregister the callback object from the handle and free the memory.


The Usage of Steam API Unregister Call Result




To use Steam API Unregister Call Result, you need to pass the same callback object and handle that you used with CALL_RESULT() and Set(). For example, if you have this code:



CRequestLeaderboardEntryCallback g_RequestLeaderboardEntryCallback; CALL_RESULT( g_RequestLeaderboardEntryCallback ); SteamAPICall_t hSteamAPICall = SteamUserStats()->FindLeaderboard( "Global Leaderboard" ); g_RequestLeaderboardEntryCallback.Set( hSteamAPICall );


You can use Steam API Unregister Call Result like this:



SteamAPI_UnregisterCallResult( &g_RequestLeaderboardEntryCallback, hSteamAPICall );


You should use Steam API Unregister Call Result before the result is ready, otherwise it will have no effect. You can check if the result is ready by using SteamUtils()->IsAPICallCompleted(). For example, you can do something like this:



if ( !SteamUtils()->IsAPICallCompleted( hSteamAPICall, NULL ) ) SteamAPI_UnregisterCallResult( &g_RequestLeaderboardEntryCallback, hSteamAPICall );


You can also use Steam API Unregister Call Result in the destructor of your callback object, if you want to make sure that it is always unregistered when the object is destroyed. For example, you can do something like this:



class CRequestLeaderboardEntryCallback : public CCallbackBase public: CRequestLeaderboardEntryCallback() m_iCallback = LeaderboardFindResult_t::k_iCallback; CRequestLeaderboardEntryCallback() SteamAPI_UnregisterCallResult( this, m_hAPICall ); void Run( void *pvParam ) LeaderboardFindResult_t *pParam = (LeaderboardFindResult_t *)pvParam; // Handle the result here void Set( SteamAPICall_t hAPICall ) m_hAPICall = hAPICall; CCallbackBase::SetGameserverFlag(); CCallbackBase::Set( hAPICall ); private: SteamAPICall_t m_hAPICall; ;


How Steam API Unregister Call Result Affects Your Game




The Benefits of Steam API Unregister Call Result




Using Steam API Unregister Call Result can have several benefits for your game, such as:



  • Improving stability: By using Steam API Unregister Call Result, you can avoid memory leaks and dangling pointers that can cause crashes or errors in your game.



  • Improving efficiency: By using Steam API Unregister Call Result, you can reduce the memory usage and CPU cycles that are wasted on unnecessary callbacks and result processing.



  • Improving user experience: By using Steam API Unregister Call Result, you can avoid unwanted or outdated results that can confuse or frustrate your users. For example, if your user requests a leaderboard entry but then cancels it or leaves the screen, you don't want to show them a result that they don't care about anymore.



The Drawbacks of Steam API Unregister Call Result




Using Steam API Unregister Call Result can also have some drawbacks for your game, such as:



  • Increasing complexity: By using Steam API Unregister Call Result, you need to keep track of your callback objects and handles and make sure that they are always unregistered when they are not needed. This can add some complexity and overhead to your game code.



  • Causing inconsistency: By using Steam API Unregister Call Result, you may end up with inconsistent or incomplete results if you unregister a callback object that is still waiting for a result from another subsystem or service. For example, if you request a leaderboard entry and an encrypted app ticket for the same user, but then unregister the callback object for the leaderboard entry, you may not get the app ticket result either.



  • Causing errors: By using Steam API Unregister Call Result, you may cause errors or exceptions if you pass invalid or mismatched parameters to the function. For example, if you pass a null pointer or a handle that does not belong to the callback object, you may get an assertion failure or a segmentation fault.



The Best Practices of Steam API Unregister Call Result




To avoid the drawbacks and maximize the benefits of Steam API Unregister Call Result, you should follow some best practices when using it, such as:



  • Use it only when necessary: You don't need to use Steam API Unregister Call Result for every asynchronous function call. You only need to use it when you are sure that you don't need or want the result anymore, or when you want to cancel the request.



  • Use it as soon as possible: You should use Steam API Unregister Call Result as soon as you know that you don't need or want the result anymore, or when you want to cancel the request. This way, you can free the memory and avoid unnecessary callbacks as soon as possible.



  • Use it consistently: You should use Steam API Unregister Call Result consistently and symmetrically with CALL_RESULT() and Set(). For every callback object and handle pair that you create with CALL_RESULT() and Set(), you should also use Steam API Unregister Call Result to unregister them when they are not needed.



  • Use it correctly: You should use Steam API Unregister Call Result correctly and carefully with valid and matching parameters. You should always pass the same callback object and handle that you used with CALL_RESULT() and Set(). You should also check if the result is ready before using Steam API Unregister Call Result, and handle any errors or exceptions that may occur.



Examples of Steam API Unregister Call Result in Action




Example 1: Getting a Leaderboard Entry for a User




In this example, we will show how to use Steam API Unregister Call Result to get a leaderboard entry for a user. We will use C++ code snippets to illustrate the process.


First, we need to define a callback object that inherits from CCallbackBase and implements a function that will be called when the result is ready. We will also store the SteamAPICall_t handle as a member variable, and use a constructor and a destructor to register and unregister the callback object. For example:



class CGetLeaderboardEntryCallback : public CCallbackBase public: CGetLeaderboardEntryCallback() m_iCallback = LeaderboardScoresDownloaded_t::k_iCallback; CGetLeaderboardEntryCallback() SteamAPI_UnregisterCallResult( this, m_hAPICall ); void Run( void *pvParam ) LeaderboardScoresDownloaded_t *pParam = (LeaderboardScoresDownloaded_t *)pvParam; // Handle the result here void Set( SteamAPICall_t hAPICall ) m_hAPICall = hAPICall; CCallbackBase::SetGameserverFlag(); CCallbackBase::Set( hAPICall ); private: SteamAPICall_t m_hAPICall; ;


Next, we need to create an instance of the callback object and use it with CALL_RESULT() and Set(). We also need to call an asynchronous function that requests a leaderboard entry for a user. For example:



CGetLeaderboardEntryCallback g_GetLeaderboardEntryCallback; CALL_RESULT( g_GetLeaderboardEntryCallback ); SteamAPICall_t hSteamAPICall = SteamUserStats()->DownloadLeaderboardEntries( hLeaderboard, k_ELeaderboardDataRequestGlobalAroundUser, -4, 4 ); g_GetLeaderboardEntryCallback.Set( hSteamAPICall );


This way, when the result of DownloadLeaderboardEntries() is ready, the function CGetLeaderboardEntryCallback::Run() will be called with a parameter of type LeaderboardScoresDownloaded_t, which contains the result data. For example, we can do something like this:



void CGetLeaderboardEntryCallback::Run( void *pvParam ) LeaderboardScoresDownloaded_t *pParam = (LeaderboardScoresDownloaded_t *)pvParam; if ( pParam->m_bSuccess ) // Get the user's rank, score, and details int nRank = 0; int32 nScore = 0; int32 nDetails[3] = 0; SteamUserStats()->GetDownloadedLeaderboardEntry( pParam->m_hSteamLeaderboardEntries, 4, NULL, &nScore, nDetails, 3 ); // Display the result to the user printf( "Your rank is %d, your score is %d, and your details are %d, %d, and %d.\n", nRank, nScore, nDetails[0], nDetails[1], nDetails[2] ); else // Handle the error printf( "Failed to get leaderboard entry.\n" );


Finally, we need to use Steam API Unregister Call Result to unregister the callback object from the handle when we don't need it anymore. For example, we can do this when the user quits the game or switches to another screen. For example:



if ( !SteamUtils()->IsAPICallCompleted( hSteamAPICall, NULL ) ) SteamAPI_UnregisterCallResult( &g_GetLeaderboardEntryCallback, hSteamAPICall );