Available Services Check
From GameSpy SDK
Available Services Check
Overview
The GameSpy SDKs provide a way to check if a game's backend services are available. Any application that uses these services must first check if they are available before using the actual SDKs. The check does not need to be made before using SDKs which do not communicate with the GameSpy backend (currently Chat, GHTTP, GT2, and Voice). If you attempt to use an SDK that does communicate with the backend before checking that the backend is currently available, the SDK will fail to initialize.
The file available.h, included in the goacommon.zip, has the necessary function prototypes for making the availability check. available.c is the source file, and should generally be compiled directly into your project (along with the rest of the GameSpy code being used). To start the availability check simply call GSIStartAvailableCheck(), passing it your gamename. This will initiate a request with the backend to see if your game's backend services are available. After initiating the request, GSIAvailableCheckThink() should be called to let the code process incoming replies and send retries. It should be continued to be called as long as it returns GSIACWsaiting. It is not very time-sensitive, so it does not need to be called more frequently than every 100ms (although it can be). If the check needs to be aborted for any reason, for example due to the player leaving the online area of the game, GSICancelAvailableCheck() should be called to do any needed cleanup.
As soon as GSIAvailableCheckThink() returns any value other than GSIACWaiting, the check has completed. No extra cleanup is needed. The return value indicates the result of the check. If it is GSIACAvailable then the game's backend services are available, and the game can continue to use the GameSpy SDKs normally. If the return value is GSIACUnavailable or GSIACTemporarilyUnavailable, then the game's backend services are not available, and the game should not use any GameSpy SDKs that rely on backend services. If the user attempts to use online aspects of the game that are not available, the game should show appopriate messaging to the user. If the return value was GSIACUnavailable, then the game should inform the user that the game's online component is no longer supported. If the return value was GSIACTemporarilyUnavailable, then the game should inform the user that the game's online component is currently unavailable and they should try again later.
GSIACAvailable will also be returned from GSIAvailableCheckThink() if no response is received from the request initiated by GSIStartAvailableCheck(). In other words, if it cannot be determined if the backend is available, the safe assumption that it is available is made. The case of a failed initialization or connection for each of the individual SDKs should always be handled.
GSIAvailableCheckThink Return Values:
- GSIACWaiting
Continue to call GSIAvailableCheckThink. Processing has not yet completed.
- GSIACAvailable
This game's backend services are available. Continue normal operations. - GSIACUnavailable
This game's backend services are not available. Game play will not be possible for an extended length of time or indefinitely. This should only occur when a service has been discontinued because the developer or publisher has chosen to not renew the service.PC games will continue to be supported in GameSpy’s Arcade.
- GSIACTemporarilyUnavailable
This game's backend services are temporarily unavailable. Reserved for scheduled downtime. Services should be restored momentarily.
Game UI
The SDK does not make any assumptions or requirements as to what messages should be displayed to the users. Developers are free to implement whatever appropriate messages they wish. What the message should say will be dependent on several factors including the return value and if the developer or publisher has opted to not take the co-branding discounts.
We recommend that developers implement generalized messages, for example:
If GSIAvailableCheckThink returns with as Unavailable a suitable messages might be:
- "Online support for Tony Hawk: Underground is no longer available."
- "Midwaysports.net is no longer available for Blitz 2010."
If GSIAvailableCheckThink returns with as TemporarilyUnavailable a suitable message might be:
- "Online play for Hidden and Dangerous is temporarily unavailable do to maintenance."
- "Midwaysposrts.net is temporarily unavailable. Please try again soon."