IGameExplorer::AddGame Method

Article
10/18/2012

Registers an instance of a game with Games Explorer and either uses a custom InstanceID or returns a generated InstanceID.

Syntax

HRESULT AddGame(
         const BSTR bstrGDFBinaryPath,
         const BSTR bstrGameInstallDirectory,
         GAME_INSTALL_SCOPE installScope,
         GUID* pguidInstanceID
)

Parameters

bstrGDFBinaryPath
[in] A BSTR that contains the fully qualified path of the binary file that contains the game definition file (GDF).
bstrGameInstallDirectory
[in] A BSTR that contains the path to the game's installation folder. For legacy games, this folder must match the folder in the Microsoft legacy database. For more details, contact the Microsoft Windows Gaming and Graphics Developer Relations Group.
installScope
[in] GAME_INSTALL_SCOPE that defines whether the game is to be installed for all users or only the current user. If set to GIS_ALL_USERS, administrative access is required. If set to GIS_CURRENT_USER, administrative access is not required.
pguidInstanceID
[in, out] A pointer to a GUID to emit or receive the InstanceID associated with the game.

Return Value

This function returns an HRESULT. Use the SUCCEEDED and FAILED macros to test the return value of this function.

AddGame returns S_FALSE if the game was already installed on the system. This situation occurs if a game is added more than once with the same ApplicationID and GameInstallDirectory; that is, AddGame is called twice for the same game installed in the same folder.

Remarks

Note

This function can cause lockdown by parental controls, rendering the game's directory unusable, so it must be one of the last steps in your installation phase.

Callers should store the instanceID returned by this call, as it is necessary to call IGameExplorer::RemoveGame or IGameExplorer::UpdateGame, and to create tasks for the game in Games Explorer.

If a pointer to a GUID_NULL is passed, this method creates and returns an InstanceID for the caller.

If a pointer to an actual GUID value is passed in, this method uses that GUID as the InstanceID. If that InstanceID already exists on the system, the call fails with E_INVALIDARG.

It is not necessarily an error to call this function on a title that is already installed on the system, since titles can have multiple instances on the same system.

This method can also upgrade an older game that is no longer supported to a newer, supported version. To achieve that, please make sure that the GDF has the same gameID attribute as was used for Games Explorer's legacy game services.

Requirements

Header: Declared in GameUX.h.

Partager via