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 Syncing 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