IGameExplorer::AddGame 

  • Article

IGameExplorer::AddGame

Note    This documentation is preliminary and is subject to change.

Registers an instance of a game with the 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 that contains the game definition file (GDF).
  • bstrGameInstallDirectory
    [in] A string that contains the path to the game install folder.
  • installScope
    [in] GAME_INSTALL_SCOPE that defines whether the game is installed for all users or only the current user installing the game. If set to GIS_ALL_USERS, Administrator access is required. If set to GIS_CURRENT_USER, Administrator access is not required.
  • pguidInstanceID
    [in, out] A pointer to a GUID to emit/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.

Note    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, i.e., AddGame is called twice for the same game installed in the same folder.

Remarks

Note    This function can cause parental control lockdown, so it must be one of the last steps in your installation phase as it may render the game's directory unusable. For a list of installation steps, see Getting Started.

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

If the call is made to upgrade a legacy title to a supported title the ID returned in pguidInstanceID will be the same as the legacy entry.

If a pointer to a GUID_NULL is passed in, the API will create and return back an InstanceID for the caller.

If a pointer to an actual GUID value is passed in, the API will use that GUID as the InstanceID. If that InstanceID already exists on the system the call will fail with E_INVALIDARG.

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

Requirements

Header: Declared in GameUX.h.

See Also

GAME_INSTALL_SCOPE