XStoreQueryProductsAsync

返回与当前游戏关联的指定产品的清单信息，无论这些产品当前是否可以在当前游戏内购买。

语法

HRESULT XStoreQueryProductsAsync(  
         const XStoreContextHandle storeContextHandle,  
         XStoreProductKind productKinds,  
         const char** storeIds,  
         size_t storeIdsCount,  
         const char** actionFilters,  
         size_t actionFiltersCount,  
         XAsyncBlock* async  
)  

参数

storeContextHandle _In_
类型：XStoreContextHandle

XStoreCreateContext 返回的用户的应用商店上下文句柄。

productKinds _In_
类型：XStoreProductKind

要返回的产品类型。

storeIds _In_z_count_(storeIdsCount)
类型：char**

要检索的产品的 ID。

storeIdsCount _In_
类型：size_t

storeIds 中的 ID 数。

actionFilters _In_opt_z_count_(actionFiltersCount)
类型：char**

按产品文档中存储的某些操作限制结果。 默认情况下，此 API 返回所有产品（即使无法购买它们），但是如果您只想返回可购买的产品，可以将此限制为“购买”。如果只想返回可授予许可证的产品，可将其限制为“许可证”。 其他操作筛选器包括“完成”、“浏览”、“安排”、“详细信息”和“兑换”。

actionFiltersCount _In_
类型：size_t

actionFilters 中的筛选器数。

async _Inout_
类型：XAsyncBlock*

用于定义正在进行的异步工作的 XAsyncBlock。 XAsyncBlock 可用于轮询调用的状态和检索调用结果。 有关详细信息，请参阅 XAsyncBlock。

返回值

类型：HRESULT

HRESULT 成功或错误代码。

备注

要检索清单信息以及此函数的执行结果，请在调用此函数后调用 XStoreQueryProductsResult。

要检索当前可从当前游戏内购买的所有产品的信息，请改用 XStoreQueryAssociatedProductsAsync 方法。

以下代码段显示一个示例，用于检索与当前游戏关联的指定产品的清单信息。

void ProcessResults(XStoreProductQueryHandle queryHandle, XTaskQueueHandle taskQueueHandle)
{
    HRESULT hr = XStoreEnumerateProductsQuery(
        queryHandle,
        nullptr,
        EnumerateProductsQueryCallback);

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

    bool hasMorePages = XStoreProductsQueryHasMorePages(queryHandle);
    if (hasMorePages)
    {
        auto asyncInner = std::make_unique<XAsyncBlock>();
        ZeroMemory(asyncInner.get(), sizeof(*asyncInner));
        asyncInner->queue = taskQueueHandle;
        asyncInner->callback = ProductsQueryNextPageCallback;

        hr = XStoreProductsQueryNextPageAsync(
            queryHandle,
            asyncInner.get());

        if (FAILED(hr))
        {
            printf("Failed to get next page of products: 0x%x\r\n", hr);
            XStoreCloseProductsQueryHandle(queryHandle);
            return;
        }
    }

    XStoreCloseProductsQueryHandle(queryHandle);
}

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

    HRESULT hr = XStoreQueryProductsResult(
        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);
    ProcessResults(queryHandle, taskQueueHandle);
}

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

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

    const char* storeIds[] =
    {
        "9YYYYYYYYYYY",
        "9ZZZZZZZZZZZ",
    };

    // This is only needed if you want to restrict to items that are currently purchasable.
    // If you want items that have been sold in the past,
    // but are no longer available for purchase, then
    // pass in nullptr or an empty array for the actionFilters.
    const char* actionFilters[] =
    {
        "Purchase"
    };

    HRESULT hr = XStoreQueryProductsAsync(
        storeContextHandle,
        allProductKinds,
        storeIds,
        ARRAYSIZE(storeIds),
        actionFilters,
        ARRAYSIZE(actionFilters),
        asyncBlock.get());

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

    // Wait a while for the callbacks to run
    XAsyncGetStatus(async.get(), true);
}

要求

头文件：XStore.h（包含在 XGameRuntime.h 中）

库：xgameruntime.lib

支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机

另请参阅

XStoreXStoreQueryProductsResult
XStoreQueryAssociatedProductsAsync
XStoreQueryEntitledProductsAsync
XStoreQueryProductsAsync
XStoreQueryProductForCurrentGameAsync
XStoreQueryProductForPackageAsync