XStoreQueryEntitledProductsAsync

Article
06/22/2023

Provides the store product information for all add-ons, DLC, and consumables related to the current game that the user has an entitlement to.

Syntax

HRESULT XStoreQueryEntitledProductsAsync(  
         const XStoreContextHandle storeContextHandle,  
         XStoreProductKind productKinds,  
         uint32_t maxItemsToRetrievePerPage,  
         XAsyncBlock* async  
)

Parameters

storeContextHandle _In_
Type: XStoreContextHandle

The store context handle for the user returned by XStoreCreateContext.

productKinds _In_
Type: XStoreProductKind

The kind of products to query.

maxItemsToRetrievePerPage _In_
Type: uint32_t

Maximum number of items to retrieve per page. Passing more than 25 items per page will result in multiple service round trips being required for each page.

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

S_OK on success; otherwise, returns an error code.

Remarks

To retrieve the store product information as well as the execution result of this function call XStoreQueryEntitledProductsResult after calling this function. XStoreQueryEntitledProductsResult should be executed in the callback function for XStoreQueryEntitledProductsAsync.

Important

A product query may be returned over multiple pages even if the number of results are less than maxItemsToRetrievePerPage. You must check for additional product entries and read it by calling XStoreProductsQueryHasMorePages and XStoreProductsQueryNextPageAsync respectively.

There is no way to know the number of products that will be returned by this query upfront.

The following code snippet provides an example of retrieving store product information based on the users entitlements to related content of the current game.

void CALLBACK QueryEntitledProductsCallback(XAsyncBlock* asyncBlock)
{
    XStoreProductQueryHandle queryHandle = nullptr;

    HRESULT hr = XStoreQueryEntitledProductsResult(
        asyncBlock,
        &queryHandle);

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

    XTaskQueueHandle taskQueueHandle = reinterpret_cast<XTaskQueueHandle>(asyncBlock->context);
    //Perform desired operations using the results. Make sure to check for more pages.
}

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

    XStoreProductKind allProductKinds =
        XStoreProductKind::Consumable |
        XStoreProductKind::Durable |
        XStoreProductKind::Game |
        XStoreProductKind::Pass |
        XStoreProductKind::UnmanagedConsumable;

    HRESULT hr = XStoreQueryEntitledProductsAsync(
        storeContextHandle,
        allProductKinds,
        25,     // Max items per page
        asyncBlock.get());

    if (FAILED(hr))
    {
        printf("Failed to get user collection: 0x%x\r\n", hr);
        return;
    }
    
    if(FAILED(XAsyncGetStatus(asyncBlock, true))) 
    { 
        printf("XStoreQueryEntitledProductsAsync failed\r\n"); 
        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