跳转到主要内容

XStoreQueryAssociatedProductsAsync

获取用户可以在当前游戏中购买的产品的应用商店列表信息。

语法

参数

storeContextHandle   _In_
类型:XStoreContextHandle
由 XStoreCreateContext 返回的用户的应用商店上下文句柄。 productKinds   _In_
类型:XStoreProductKind
要返回的产品类型。 maxItemsToRetrievePerPage   _In_
类型:uint32_t
每页要检索的最大项数。 每页返回的项数可能从 0 到 maxItemsToRetrievePerPage 之间变化。 有关详细信息,请参阅分页。 async   _Inout_
类型:XAsyncBlock*
定义正在执行的异步工作的 XAsyncBlock。 使用 XAsyncBlock 轮询调用状态并检索调用结果。 有关详细信息,请参阅 XAsyncBlock。

返回值

类型:HRESULT HRESULT 成功或错误代码。

备注

要获取应用商店列表信息和此函数的执行结果,请在调用此函数后调用 XStoreQueryAssociatedProductsResult。 XStoreQueryAssociatedProductsResult 包含一个可通过调用 XStoreEnumerateProductsQuery 进行枚举的 XStoreProductQueryHandle。 你无法预先知道此查询返回的产品数量。 此 API 仅返回用户可以在 Microsoft Store 中浏览或在游戏中购买的产品。 结果不包括任何被隐藏、已过期或已从应用商店中移除的产品。 如果需要此类产品的详细信息,请使用 XStoreQueryProductsAsync 并传入该产品的应用商店 ID。

分页

此函数跨多个页面返回产品(每页最多 maxItemsToRetrievePerPage 项)。 使用 XStoreProductsQueryHasMorePages 和 XStoreProductsQueryNextPageAsync/XStoreProductsQueryNextPageResult 来处理所有分页结果。 分页只有在 XStoreProductsQueryHasMorePages 返回 false 时才算完成。
沙盒和 RETAIL 之间的分页行为可能有所不同。 在沙盒中,项会累积至 maxItemsToRetrievePerPage,然后才会返回一页。 在 RETAIL 中,通常每页返回 0-1 项。对于使用此 API 的所有游戏,在发布前实现并测试分页功能非常重要。要在沙盒中测试分页行为,请将 maxItemsToRetrievePerPage 暂时设置为小于发布到你的沙盒中的产品数量的值。 要在游戏发布前在 RETAIL 中进行测试,请使用 Partner Center 中”定价和可用性”页面上的启用私有受众选项来发布产品。 要在游戏发布后在 RETAIL 中进行测试,请使用包外部测试。
以下代码演示了如何跨多个页面检索产品查询结果。 请确保通过分页递归传递查询句柄,以避免泄漏。

要求

头文件: XStore.h(包含于 XGameRuntime.h 中) 库: xgameruntime.lib 支持的平台: Windows、XBOX One 系列主机和 XBOX Series 主机

概念文档

另请参阅

XStore
XStoreQueryAssociatedProductsResult
XStoreEnumerateProductsQuery
XStoreProductsQueryHasMorePages
XStoreProductsQueryNextPageAsync
基本应用商店操作
向玩家授予附加内容的访问权限
最后修改于 2026年10月19日