Callbacks and Call Results - adambiser/agk-steam-plugin GitHub Wiki
The Steam API uses a lot of asynchronous callbacks and call results. This means that just because RequestStats
(or Init
) was called doesn't mean that the user stats have actually been initialized by the time the call finishes. To properly handle callbacks, the RunCallbacks
method should be called when Sync
ing to allow the callbacks and callresults some time to run.
Understanding the difference between callbacks and call results is not needed when using this plugin, but generally speaking, callbacks report when a global notification has happened, such as a friend coming online, and call results report when information that the application requested has been loaded asynchronously, such as requesting the top 10 entries on a leaderboard. Both are essentially a way of notifying the application when events happen.
Since Tier 1 doesn't support events, each callback and call result handled by the plugin has a method that reports its state and should be checked each frame.
Callbacks
Callbacks are global notifications received by the application, such as a friend coming online or a laptop's low power warning.
To handle callbacks, the plugin keeps internal lists that accumulate the data reported when callbacks fire. To process these lists, each callback has a "Has...Response" method and one or more "Get" methods. The "Has...Response" method loads the data from the oldest callback response so that it can be retrieved using the callback's "Get" methods. It is possible for a callback to fire multiple times per frame, so a while loop is the best way to process a callback's data.
Example
while Steam.HasAvatarImageLoadedResponse() // Enumerate any accumulated callback data.
hSteamID as integer
hSteamID = Steam.GetAvatarImageLoadedUser()
// Reload the user's avatar...
endwhile
Call Results
Call results are also asynchronous calls, but they are more specialized. A call result method returns a handle that you use to check the status of the call result using GetCallResultCode and retrieve its data using the "Get" methods. When the call result's response has been processed by your game, you should DeleteCallResult the handle.
If GetCallResultCode returns 0, the call result is still working. Any non-zero value means that it has completed. A value of 1 (EResultOK) means the call was successful. All other values indicate failure.
Here is the complete list of result codes.
Example
#constant EResultOK 1
// Assume hLeaderboard has already been found.
callResult as integer
needToUploadScore as integer = 1
do
// Game logic...
Sync()
Steam.RunCallbacks()
// Nothing else can be done until user stats are loaded.
if Steam.StatsInitialized()
if needToUploadScore
needToUploadScore = 0
callResult = Steam.UploadLeaderboardScore(hLeaderboard, 9000)
endif
if callResult
result as integer
result = Steam.GetCallResultCode(callResult)
if result
if result = EResultOK
Message("Success!")
else
Message("Error code: " + str(result))
endif
Steam.DeleteCallResult(callResult)
callResult = 0
endif
endif
endif
loop