Share via

IGameExplorer::AddGame

  • Article
Bb173437.XDK_CHM_BANNER_left(en-us,VS.85).jpg Bb173437.XDK_CHM_BANNER_right(en-us,VS.85).jpg

IGameExplorer::AddGame

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

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

Parameters

  • bstrGDFBinaryPath
    [in] A string that contains the fully qualified path of the binary file that contains the game definition file (GDF).
  • bstrGameInstallDirectory
    [in] A string 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 Values

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. For a list of installation steps, see Getting Started With Game Explorer.

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 Game 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 (described in The Game-Definition-File (GDF) Schema) has the same gameID attribute as was used for Game Explorer's legacy game services. For more information, see Legacy Game Support. To arrange access to your game ID, contact the Microsoft.

Requirements

Header: Declared in GameUX.h.

See Also

GAME_INSTALL_SCOPE