> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XStoreQueryProductsAsync

> XStoreQueryProductsAsync

# XStoreQueryProductsAsync

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

## 语法

```cpp theme={null}
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](/reference/system/xstore/functions/xstorecreatecontext) 为用户返回的商店上下文句柄。

*productKinds*   \_In\_\
类型：[XStoreProductKind](/reference/system/xstore/enums/xstoreproductkind)

要返回的产品类型。

*storeIds*   \_In\_z\_count\_(storeIdsCount)\
类型：char\*\*

要检索的产品的商店标识符。

*storeIdsCount*   \_In\_\
类型：size\_t

**storeIds** 列表中的产品数量。
此数量不应超过 100。

*actionFilters*   \_In\_opt\_z\_count\_(actionFiltersCount)\
类型：char\*\*

按产品文档中存储的某些操作限制结果。
默认情况下，此 API 返回所有产品，即使这些产品不可购买，但你可以使用操作筛选器来限制结果。
例如，如果只想要可购买的产品，则使用 "Purchase"；如果只想要可授权的产品，则使用 "License"。
其他操作筛选器包括 "Fulfill"、"Browse"、"Curate"、"Details" 和 "Redeem"。

*actionFiltersCount*   \_In\_\
类型：size\_t

**actionFilters** 中的筛选器数量。

*async*   \_Inout\_\
类型：[XAsyncBlock\*](/reference/system/xasync/structs/xasyncblock)

定义正在完成的异步工作的 [XAsyncBlock](/reference/system/xasync/structs/xasyncblock)。
使用 [XAsyncBlock](/reference/system/xasync/structs/xasyncblock) 检查调用的状态并获取结果。
有关详细信息，请参阅 [XAsyncBlock](/reference/system/xasync/structs/xasyncblock)。

### 返回值

类型：HRESULT

HRESULT 成功或错误代码。

## 备注

调用 [XStoreQueryProductsResult](/reference/system/xstore/functions/xstorequeryproductsresult) 以检索列表信息和此函数的执行结果。

如果在请求中提供的 storeID 超过 100 个，此 API 将失败。
如果使用大型目录，请将每个查询限制为少于 100 个产品。

要获取玩家可在当前游戏中购买的所有产品的详细信息，请改用 [XStoreQueryAssociatedProductsAsync](/reference/system/xstore/functions/xstorequeryassociatedproductsasync)。

以下代码片段展示了检索与当前游戏关联的指定产品的列表信息的示例。

```cpp theme={null}

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

    if (FAILED(hr))
    {
        printf("Failed enumerate the product query handle: 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;
    }

     ProcessResults(queryHandle);
}

void QueryProducts(XStoreContextHandle storeContextHandle, XTaskQueueHandle taskQueueHandle)
{
    auto asyncBlock = std::make_unique<XAsyncBlock>();
    ZeroMemory(asyncBlock.get(), sizeof(*asyncBlock));
    asyncBlock->queue = 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;
    }
}

```

## 要求

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

**库：** xgameruntime.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 概念文档

* [基本商店操作](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-basic-store-operations)
* [授予玩家访问加载项内容的权限](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-granting-access-to-content)
* [Microsoft Store API 的精细速率限制](/publishing/xstore-commerce/xstore-fgrl)

## 另请参阅

[XStore](/reference/system/xstore/xstore_members)
[XStoreQueryProductsResult](/reference/system/xstore/functions/xstorequeryproductsresult)\
[XStoreQueryAssociatedProductsAsync](/reference/system/xstore/functions/xstorequeryassociatedproductsasync)\
[XStoreQueryEntitledProductsAsync](/reference/system/xstore/functions/xstorequeryentitledproductsasync)\
[XStoreQueryProductsAsync](/reference/system/xstore/functions/xstorequeryproductsasync)\
[XStoreQueryProductForCurrentGameAsync](/reference/system/xstore/functions/xstorequeryproductforcurrentgameasync)\
[XStoreQueryProductForPackageAsync](/reference/system/xstore/functions/xstorequeryproductforpackageasync)\
[基本商店操作](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-basic-store-operations)\
[授予玩家访问加载项内容的权限](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-granting-access-to-content)