XPackageInstallChunksAsync

Article
06/22/2023

Starts the installation of chunks.

Syntax

HRESULT XPackageInstallChunksAsync(  
         const char* packageIdentifier,  
         uint32_t selectorCount,  
         XPackageChunkSelector* selectors,  
         uint32_t minimumUpdateIntervalMs,  
         bool suppressUserConfirmation,  
         XAsyncBlock* asyncBlock  
)

Parameters

packageIdentifier _In_z_
Type: char*

A string that uniquely identifies the installed package on the disk. For more information about package identifiers, see Manage and license downloadable content (DLC).

selectorCount _In_
Type: uint32_t

The number of selectors in the selectors parameter.

selectors _In_reads_(selectorCount)
Type: XPackageChunkSelector*

An array of selectors that specify the chunks to be installed.

minimumUpdateIntervalMs _In_
Type: uint32_t

The interval between updates, in milliseconds.

suppressUserConfirmation _In_
Type: bool

If the chunks to be installed exceed a preset size, then a confirmation prompt will be displayed. If suppressUserConfirmation is true, then no prompt will be displayed and the installation will progress as if the user accepted. This lets the game present its own UI. If the game uses this, it should also call XPackageEstimateDownloadSize to get the size that will be presented to the user. XPackageEstimateDownloadSize also returns a Boolean, to indicate whether the size is large enough that a prompt is to be displayed. If a download confirmation is needed, then the game must either show it by using its own UI or let XPackageInstallChunks show it.

asyncBlock _Inout_
Type: XAsyncBlock*

An XAsyncBlock for monitoring the status of the asynchronous call.

Return value

Type: HRESULT

HRESULT success or error code.

Remarks

XPackageInstallChunks has an async variant. Installation of chunks might involve prompting the user to accept the download size.

This example shows how BigMaps are installed by using the asynchronous APIs:

void CALLBACK BigMapsInstallProgress(
    void* /* context */,
    XPackageInstallationMonitorHandle monitor)
{
    XPackageInstallationProgress progress;
    XPackageGetInstallationProgress(monitor, &progress);
    if (progress.completed)
    {
        printf("BigMaps Installed\n");
        XPackageCloseInstallationMonitorHandle(monitor);
    }
}

void CALLBACK BigMapsAsyncInstallComplete(XAsyncBlock* asyncBlock)
{
    XPackageInstallationMonitorHandle monitor;
    HRESULT hr = XPackageInstallChunksResult(asyncBlock, &monitor);
    delete asyncBlock;

    if (SUCCEEDED(hr))
    {
        XTaskQueueRegistrationToken token;
        if (FAILED(XPackageRegisterInstallationProgressChanged(
            monitor,
            nullptr,
            BigMapsInstallProgress, &token)))
        {
            XPackageCloseInstallationMonitorHandle(monitor);
        }
    }
}

HRESULT InstallBigMapsAsync(XTaskQueueHandle queue)
{
    char id[XPACKAGE_IDENTIFIER_MAX_LENGTH];
    HRESULT hr = XPackageGetCurrentProcessPackageIdentifier(_countof(id), id);
    if (FAILED(hr)) return hr;

    XPackageChunkSelector selector;
    selector.type = XPackageChunkSelectorType::Tag;
    selector.tag = "BigMaps";

    XAsyncBlock* asyncBlock = new (std::nothrow) XAsyncBlock{};
    asyncBlock->callback = BigMapsAsyncInstallComplete;
    asyncBlock->queue = queue;

    hr = XPackageInstallChunksAsync(
        id, 1, &selector, 1000,
        false, asyncBlock);

    if (FAILED(hr))
    {
        delete asyncBlock;
    }

    return hr;
}

Requirements

Header: XPackage.h

Library: xgameruntime.lib

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

Share via