XPackageEnumeratePackages

Article
11/09/2023

Finds packages that are already installed, or being installed, and are related to the calling process.

Syntax

HRESULT XPackageEnumeratePackages(  
         XPackageKind kind,  
         XPackageEnumerationScope scope,  
         void* context,  
         XPackageEnumerationCallback* callback  
)

Parameters

kind _In_
Type: XPackageKind

The type of installation packages to be enumerated.

scope _In_
Type: XPackageEnumerationScope

The scope of the installation packages.

context _In_opt_
Type: void*

Context to be passed to the callback specified in the callback parameter.

callback _In_
Type: XPackageEnumerationCallback*

A callback to be called on completion.

Return value

Type: HRESULT

HRESULT success or error code.

Remarks

Note

This function isn't safe to call on a time-sensitive thread. For more information, see Time-sensitive threads.

Use XPackageEnumeratePackages to find packages that are already installed, or being installed, and are related to the calling process. This function can find content packages as well as app packages. It provides details about an installation, through an XPackageDetails structure.

If the package is still installing, the installing property is set to true and you can create an installation monitor to let the package's identifier monitor the progress of installation.

There are no generic installation queue notifications; the intent is to use XPackageEnumeratePackages to show and track items in flight. Nor is there an API to stop, start, or cancel an installation. From a game's perspective, the installation should take care of itself. Errors are automatically retried and are invisible to the game.

The output of the API, when called with value XPackageKind::Game depending on the XPackageEnumerationScope value will be:

Scope	Franchise game hub	Hub-aware game	Hub-unaware game
ThisOnly	Only the franchise game hub	Only the hub-aware game	Only the hub-unaware game
ThisAndRelated	The franchise game hub, all the hub-aware games associated with it and all the RelatedProducts	The hub-aware game and all the RelatedProducts	The hub-unaware game and all the RelatedProducts
ThisPublisher	All the game products belonging to the same publisher as the current process	All the game products belonging to the same publisher as the current process	All the game products belonging to the same publisher as the current process

The output of the API, when called with value XPackageKind::Content depending on the XPackageEnumerationScope value will be:

Scope	Franchise game hub	Hub-aware game	Hub-unaware game
ThisOnly	The DLCs related to this franchise game hub	The DLCs related to this hub-aware game	The DLCs related to this hub-unaware game
ThisAndRelated	The DLCs related to this franchise game hub, to its hub-aware titles and to all its RelatedProducts	The DLCs related to this hub-aware game and to all its RelatedProducts	The DLCs related to this hub-unaware game and to all its RelatedProducts
ThisPublisher	All DLCs (from the same publisher or from other publishers) related to a base game from the same publisher as the current process	All DLCs (from the same publisher or from other publishers) related to a base game from the same publisher as the current process	All DLCs (from the same publisher or from other publishers) related to a base game from the same publisher as the current process

Example:

bool CALLBACK ListDlcCallback(
    void* /* context */,
    const XPackageDetails* details)
{
    printf("Found dlc: %s\n", details->displayName);
    return true; // continue enumerating
}

HRESULT ListDlc()
{
    HRESULT hr = XPackageEnumeratePackages(
        XPackageKind::Content,                      /* Looking for content packages (DLC) */
        XPackageEnumerationScope::ThisAndRelated,   /* For this game and related games*/
        nullptr, ListDlcCallback);
    return hr;
}

Requirements

Header: XPackage.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via