> ## 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.

# XStoreQueryAssociatedProductsForStoreIdAsync

> XStoreQueryAssociatedProductsForStoreIdAsync

# XStoreQueryAssociatedProductsForStoreIdAsync

Obtém informações da listagem da loja para produtos que podem ser comprados relacionados a um produto de destino especificado pela sua Store ID.

## Sintaxe

```cpp theme={null}
HRESULT XStoreQueryAssociatedProductsForStoreIdAsync(   
         const XStoreContextHandle storeContextHandle,   
         const char* storeId, 
         XStoreProductKind productKinds,   
         uint32_t maxItemsToRetrievePerPage,   
         XAsyncBlock* async   
)   
```

### Parâmetros

*storeContextHandle*   \_In\_\
Tipo: XStoreContextHandle

O identificador de contexto da loja para o usuário retornado por [XStoreCreateContext](/pt-BR/reference/system/xstore/functions/xstorecreatecontext).

*storeId*   \_In\_\
Tipo: const char\*

A Store ID do produto para o qual os produtos associados são recuperados.

*productKinds*   \_In\_\
Tipo: [XStoreProductKind](/pt-BR/reference/system/xstore/enums/xstoreproductkind)

O tipo de produtos a serem retornados.

*maxItemsToRetrievePerPage*   \_In\_\
Tipo: uint32\_t

O número máximo de itens a serem recuperados por página.
O número de itens retornados por página pode variar de 0 a `maxItemsToRetrievePerPage`.

*async*   \_Inout\_\
Tipo: [XAsyncBlock\*](/pt-BR/reference/system/xasync/structs/xasyncblock)

Um [XAsyncBlock](/pt-BR/reference/system/xasync/structs/xasyncblock) que define o trabalho assíncrono que está sendo realizado.
Use o [XAsyncBlock](/pt-BR/reference/system/xasync/structs/xasyncblock) para sondar o status da chamada e recuperar os resultados da chamada.
Para obter mais informações, consulte [XAsyncBlock](/pt-BR/reference/system/xasync/structs/xasyncblock).

### Valor retornado

Tipo: HRESULT

Código de sucesso ou erro HRESULT.

## Comentários

Para obter as informações da listagem da loja e o resultado da execução desta função, chame [XStoreQueryAssociatedProductsForStoreIdResult](/pt-BR/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult) depois de chamar esta função.
[XStoreQueryAssociatedProductsForStoreIdResult](/pt-BR/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult) contém um `XStoreProductQueryHandle` que é enumerado chamando [XStoreEnumerateProductsQuery](/pt-BR/reference/system/xstore/functions/xstoreenumerateproductsquery).

<Note>
  Esta API oferece suporte ao mesmo padrão de paginação descrito em [XStoreQueryAssociatedProductsAsync](/pt-BR/reference/system/xstore/functions/xstorequeryassociatedproductsasync).

  A paginação pode se comportar de forma diferente entre áreas restritas e RETAIL.
  Verifique sua implementação de paginação e não deixe de testar em RETAIL antes do lançamento.

  Para obter mais informações, consulte [Paginação](/pt-BR/reference/system/xstore/functions/xstorequeryassociatedproductsasync#paging).
</Note>

Não é possível saber antecipadamente o número de produtos que esta consulta retorna.

Use a API para encontrar complementos associados a um produto de destino usando a Store ID dele.
Essa capacidade é especialmente útil para hubs de jogos de franquia. Um hub de jogos de franquia pode enumerar complementos de vários jogos, mas não consegue saber a qual jogo esses complementos estão associados.

Exemplos de cenários de uso:

* Os desenvolvedores executam `XPackageEnumeratePackages` para enumerar os produtos [XPackageKind::Game](/pt-BR/reference/system/xpackage/enums/xpackagekind) instalados e, em seguida, para um desses jogos, executam `XStoreQueryAssociatedProductsForStoreIdAsync` usando a storeId obtida de `XPackageDetails`. Os desenvolvedores executam `XPackageEnumeratePackages` para [XPackageKind::Content](/pt-BR/reference/system/xpackage/enums/xpackagekind) para enumerar o DLC instalado. Os resultados da enumeração de conteúdo e da consulta de produtos são cruzados para que os desenvolvedores possam identificar quais DLCs estão instalados para o jogo específico.

* Os desenvolvedores executam `XStoreQueryAssociatedProductsAsync` para obter uma lista de produtos que podem ser comprados associados ao jogo atual. Em seguida, usando a storeId do `XStoreProduct` do jogo de destino, os desenvolvedores executam `XStoreQueryAssociatedProductsForStoreIdAsync` para descobrir quais DLCs estão associados a ele.

O snippet de código a seguir mostra um exemplo de consulta de produtos associados a um produto de destino usando a Store ID dele.
Os resultados são processados em várias páginas.

```cpp theme={null}
struct QueryContext
{
    uint32_t count = 0;  // used to accumulate count of products returned across pages
    XStoreProductQueryHandle handle = nullptr;  // handle to reuse for paged operations
};

void CleanupProductQuery(XAsyncBlock* async)
{
    if (!async) return;

    auto* ctx = static_cast<QueryContext*>(async->context);
    if (ctx)
    {
        if (ctx->handle)
        {
            XStoreCloseProductsQueryHandle(ctx->handle);
            ctx->handle = nullptr;
        }

        delete ctx;
        async->context = nullptr;
    }

    delete async;
}

bool CALLBACK ProductEnumerationCallback(const XStoreProduct* product, void* context)
{
    // Use result of query
    auto* ctx = static_cast<QueryContext*>(context);

    // Empty results are possible and should be skipped
    if (product)
    {
        printf("%s %s %u\n", product->title, product->storeId, product->productKind);
        ctx->count++;
    }

    return true;
}

void CALLBACK QueryAssociatedProductsForStoreIdCallback(XAsyncBlock* async)
{
    auto* ctx = static_cast<QueryContext*>(async->context);

    HRESULT hr = XStoreQueryAssociatedProductsForStoreIdResult(async, &ctx->handle);
    if (FAILED(hr)) { CleanupProductQuery(async); return; }

    hr = XStoreEnumerateProductsQuery(ctx->handle, ctx, ProductEnumerationCallback);
    if (FAILED(hr)) { CleanupProductQuery(async); return; }

    if (XStoreProductsQueryHasMorePages(ctx->handle))
    {
        QueryNextPage(async);
        return;
    }

    printf("Enumeration complete, %u products found\n", ctx->count);
    CleanupProductQuery(async);
}

void QueryAssociatedProductsForStoreId(XStoreContextHandle storeContextHandle, XTaskQueueHandle taskQueueHandle, const char* storeId)
{
    auto async = new XAsyncBlock{};
    async->context = new QueryContext{ 0, nullptr };
    async->queue = taskQueueHandle; 
    async->callback = QueryAssociatedProductsForStoreIdCallback; 
 
    XStoreProductKind typeFilter = 
        XStoreProductKind::Consumable | 
        XStoreProductKind::Durable | 
        XStoreProductKind::Game |
        XStoreProductKind::Pass |
        XStoreProductKind::UnmanagedConsumable;
 
    HRESULT hr = XStoreQueryAssociatedProductsForStoreIdAsync( 
        storeContextHandle, 
        storeId, 
        typeFilter, 
        25,           // Products per page (25 is a good default, can set lower to verify paging in sandbox)
        async);

    if (FAILED(hr))
    {
        printf("Failed to get associated products for %s: 0x%x\r\n", storeId, hr); 
        CleanupProductQuery(async);
    }
}

// In RETAIL, content will be returned across multiple pages.
// Paging is not complete until XStoreProductsQueryHasMorePages returns false.
void QueryNextPage(XAsyncBlock *async)
{
    async->callback = [](XAsyncBlock* async)
    {
        auto* ctx = static_cast<QueryContext*>(async->context);

        XStoreProductQueryHandle next = nullptr;
        HRESULT hr = XStoreProductsQueryNextPageResult(async, &next);
        if (FAILED(hr)) { CleanupProductQuery(async); return; }

        // Safe swap: avoids leaks if 'next' is a new handle, avoids double-close if identical
        if (next && next != ctx->handle)
        {
            if (ctx->handle) XStoreCloseProductsQueryHandle(ctx->handle);
            ctx->handle = next;
        }
        else
        {
            ctx->handle = next; // covers null or same-handle cases
        }

        hr = XStoreEnumerateProductsQuery(ctx->handle, ctx, ProductEnumerationCallback);
        if (FAILED(hr)) { CleanupProductQuery(async); return; }

        if (XStoreProductsQueryHasMorePages(ctx->handle))
        {
            QueryNextPage(async);
            return;
        }

        printf("Enumeration complete, %u products found\n", ctx->count);
        CleanupProductQuery(async);
    };

    auto* ctx = static_cast<QueryContext*>(async->context);
    HRESULT hr = XStoreProductsQueryNextPageAsync(ctx->handle, async);
    if (FAILED(hr))
    {
        CleanupProductQuery(async);
    }
}

```

## Requisitos

**Cabeçalho:** XStore.h (incluído em XGameRuntime.h)

**Biblioteca:** xgameruntime.lib

**Plataformas com suporte:** Windows, consoles da família XBOX One e consoles XBOX Series

## Documentação conceitual

* [Operações básicas da loja](/pt-BR/publishing/xstore-commerce/xstore-basic-operations)

## Confira também

[XStore](/pt-BR/reference/system/xstore/xstore_members)\
[XStoreQueryAssociatedProductsForStoreIdResult](/pt-BR/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult)\
[XStoreQueryAssociatedProductsAsync](/pt-BR/reference/system/xstore/functions/xstorequeryassociatedproductsasync)\
[XStoreEnumerateProductsQuery](/pt-BR/reference/system/xstore/functions/xstoreenumerateproductsquery)\
[XStoreProductsQueryHasMorePages](/pt-BR/reference/system/xstore/functions/xstoreproductsqueryhasmorepages)\
[XStoreProductsQueryNextPageAsync](/pt-BR/reference/system/xstore/functions/xstoreproductsquerynextpageasync)


## Related topics

- [XStoreQueryAssociatedProductsForStoreIdAsync](/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidasync.md)
- [XStoreQueryAssociatedProductsForStoreIdResult](/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult.md)
- [Basic store operations](/publishing/xstore-commerce/xstore-basic-operations.md)
- [基本的な Store 操作](/ja-jp/publishing/xstore-commerce/xstore-basic-operations.md)
- [商店基本操作](/zh-CN/publishing/xstore-commerce/xstore-basic-operations.md)