XStoreQueryEntitledProductsAsync
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
See also
XStore
XStoreQueryEntitledProductsResult
XStoreQueryAssociatedProductsAsync
XStoreQueryEntitledProductsAsync
XStoreQueryProductsAsync
XStoreQueryProductForCurrentGameAsync
XStoreQueryProductForPackageAsync