XStoreAcquireLicenseForPackageAsync

Article
06/22/2023

Acquires a license to an installed DLC package (Durable with a package product type) for the current game that the user is entitled to use.

XStoreRegisterPackageLicenseLost can be used to monitor if the license obtained from this API is lost.

Note

This API will not work with Durable add-ons without a package. To get the license for Durables without a package use XStoreAcquireLicenseForDurablesAsync.

Syntax

HRESULT XStoreAcquireLicenseForPackageAsync(  
         const XStoreContextHandle storeContextHandle,  
         const char* packageIdentifier,  
         XAsyncBlock* async  
)

Parameters

storeContextHandle _In_
Type: XStoreContextHandle

The store context handle for the user returned by XStoreCreateContext.

packageIdentifier _In_z_
Type: char*

A string that uniquely identifies a store package. This is typically returned as part of an XPackageEnumeratePackages operation. For more information about package identifiers, see Manage and license downloadable content (DLC).

async _Inout_
Type: XAsyncBlock*

An XAsyncBlock defining the asynchronous work being done. The XAsyncBlock can be used to poll for the call's status and retrieve call results. See XAsyncBlock for more information.

Return value

Type: HRESULT

HRESULT success or error code.

Error code	Description
0x89245208 `E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER`	Package for this product is not installed, or this is being called on a Durable without a package type (use XStoreAcquireLicenseForDurablesAsync instead).

Remarks

To retrieve the package license as well as the execution result of this function call XStoreAcquireLicenseForPackageResult after calling this function. If you would like to check if a package can be licensed then call XStoreCanAcquireLicenseForPackageAsync. After acquiring a license you must check if it is valid by calling XStoreIsLicenseValid.

The code snippet below shows an example of using the following APIs.

void CALLBACK PackageLicenseLostCallback(void* context)
{
    printf("**** License Lost ****\r\n");
}

void CALLBACK AcquireLicenseForPackageCallback(XAsyncBlock* asyncBlock)
{
    XStoreLicenseHandle licenseHandle = nullptr;

    HRESULT hr = XStoreAcquireLicenseForPackageResult(
        asyncBlock,
        &licenseHandle);

    if (FAILED(hr))
    {
        printf("Failed retrieve the license handle: 0x%x\r\n", hr);
        return;
    }

    bool isValid = XStoreIsLicenseValid(licenseHandle);
    printf("isValid: %s\r\n", isValid ? "true" : "false");

    if (isValid)
    {
        XTaskQueueHandle taskQueueHandle = reinterpret_cast<XTaskQueueHandle>(asyncBlock->context);
        XTaskQueueRegistrationToken token = { 0 };

        //  Todo: Save the licenseHandle to hold onto it for the life of the app or until you unload the package.
        // This allows us to be notified if the license becomes invalid and we need to handle unloading the content.
        hr = XStoreRegisterPackageLicenseLost(
            licenseHandle,
            taskQueueHandle,
            nullptr,
            PackageLicenseLostCallback,
            &token);

        if (FAILED(hr))
        {
            XStoreCloseLicenseHandle(licenseHandle);
            printf("Failed register license lost callback: 0x%x\r\n", hr);
            return;
        }

        // This would normally go in your cleanup code when releasing the license
        hr = XStoreUnregisterPackageLicenseLost(
            licenseHandle,
            token,
            true);

        if (FAILED(hr))
        {

            // This would normally go in your cleanup code when releasing the license
            XStoreCloseLicenseHandle(licenseHandle);
            printf("Failed unregister license lost callback: 0x%x\r\n", hr);
            return;
        }
    }

    XStoreCloseLicenseHandle(licenseHandle);
}

void AcquireLicenseForPackage(XStoreContextHandle storeContextHandle, XTaskQueueHandle taskQueueHandle, const char* packageIdentifier)
{
    auto asyncBlock = std::make_unique<XAsyncBlock>();
    ZeroMemory(asyncBlock.get(), sizeof(*asyncBlock));
    asyncBlock->queue = taskQueueHandle;
    asyncBlock->context = taskQueueHandle;
    asyncBlock->callback = AcquireLicenseForPackageCallback;

    HRESULT hr = XStoreAcquireLicenseForPackageAsync(
        storeContextHandle,
        packageIdentifier,
        asyncBlock.get());

    if (FAILED(hr))
    {
        printf("Failed to get product for package: 0x%x\r\n", hr);
        return;
    }
}

Requirements

Header: XStore.h (included in XGameRuntime.h)

Library: xgameruntime.lib

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

Share via