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

Obtiene información de descripción de la Store de los productos que se pueden comprar relacionados con un producto de destino especificado por su identificador de la tienda.

## Sintaxis

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

### Parámetros

*storeContextHandle*   \_In\_\
Tipo: XStoreContextHandle

El identificador del contexto de la tienda para el usuario devuelto por [XStoreCreateContext](/es/reference/system/xstore/functions/xstorecreatecontext.md).

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

El identificador de la tienda del producto para el que se recuperan los productos asociados.

*productKinds*   \_In\_\
Tipo: [XStoreProductKind](/es/reference/system/xstore/enums/xstoreproductkind.md)

El tipo de productos que se van a devolver.

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

El número máximo de elementos que se recuperarán por página.
El número de elementos devueltos por página puede variar de 0 a `maxItemsToRetrievePerPage`.

*async*   \_Inout\_\
Tipo: [XAsyncBlock\*](/es/reference/system/xasync/structs/xasyncblock.md)

Un [XAsyncBlock](/es/reference/system/xasync/structs/xasyncblock.md) que define el trabajo asincrónico que se está realizando.
Use el [XAsyncBlock](/es/reference/system/xasync/structs/xasyncblock.md) para sondear el estado de la llamada y recuperar los resultados de la llamada.
Para obtener más información, consulte [XAsyncBlock](/es/reference/system/xasync/structs/xasyncblock.md).

### Valor devuelto

Tipo: HRESULT

HRESULT de operación correcta o código de error.

## Comentarios

Para obtener la información de descripción de la Store y el resultado de la ejecución de esta función, llame a [XStoreQueryAssociatedProductsForStoreIdResult](/es/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult.md) después de llamar a esta función.
[XStoreQueryAssociatedProductsForStoreIdResult](/es/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult.md) contiene un `XStoreProductQueryHandle` que se enumera llamando a [XStoreEnumerateProductsQuery](/es/reference/system/xstore/functions/xstoreenumerateproductsquery.md).

> [!NOTE]
>
> Esta API admite el mismo patrón de paginación que se describe en [XStoreQueryAssociatedProductsAsync](/es/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md).
>
> La paginación puede comportarse de forma diferente entre los sandboxes y RETAIL.
> Compruebe su implementación de la paginación y asegúrese de probarla en RETAIL antes del lanzamiento.
>
> Para obtener más información, consulte [Paginación](/es/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md#paging).

No es posible conocer de antemano el número de productos que devuelve esta consulta.

Use la API para encontrar complementos asociados a un producto de destino mediante su identificador de la tienda.
Esta capacidad es especialmente útil para los Franchise Game Hubs. Un Franchise Game Hub puede enumerar complementos de varios juegos, pero no puede indicar a qué juego están asociados estos complementos.

Ejemplos de escenarios de uso:

* Los desarrolladores ejecutan `XPackageEnumeratePackages` para enumerar los productos [XPackageKind::Game](/es/reference/system/xpackage/enums/xpackagekind.md) instalados y, después, para uno de esos juegos, ejecutan `XStoreQueryAssociatedProductsForStoreIdAsync` con el storeId obtenido de `XPackageDetails`. Los desarrolladores ejecutan `XPackageEnumeratePackages` para [XPackageKind::Content](/es/reference/system/xpackage/enums/xpackagekind.md) para enumerar los DLC instalados. Los resultados de la enumeración de contenido y de la consulta de productos se cruzan para que los desarrolladores puedan identificar ahora qué DLC están instalados para el juego específico.

* Los desarrolladores ejecutan `XStoreQueryAssociatedProductsAsync` para obtener una lista de los productos que se pueden comprar asociados al juego actual. Después, con el storeId del `XStoreProduct` del juego de destino, los desarrolladores ejecutan `XStoreQueryAssociatedProductsForStoreIdAsync` para averiguar qué DLC están asociados a él.

El siguiente fragmento de código muestra un ejemplo de consulta de productos asociados a un producto de destino mediante su identificador de la tienda.
Los resultados se procesan en varias 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

**Encabezado:** XStore.h (incluido en XGameRuntime.h)

**Biblioteca:** xgameruntime.lib

**Plataformas compatibles:** Windows, consolas de la familia XBOX One y consolas XBOX Series

## Documentación conceptual

* [Operaciones básicas de la tienda](/es/publishing/xstore-commerce/xstore-basic-operations.md)

## Consulte también

[XStore](/es/reference/system/xstore/xstore_members.md)\
[XStoreQueryAssociatedProductsForStoreIdResult](/es/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult.md)\
[XStoreQueryAssociatedProductsAsync](/es/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md)\
[XStoreEnumerateProductsQuery](/es/reference/system/xstore/functions/xstoreenumerateproductsquery.md)\
[XStoreProductsQueryHasMorePages](/es/reference/system/xstore/functions/xstoreproductsqueryhasmorepages.md)\
[XStoreProductsQueryNextPageAsync](/es/reference/system/xstore/functions/xstoreproductsquerynextpageasync.md)


## Related topics

- [XStoreQueryAssociatedProductsForStoreIdResult](/es/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult.md)
- [Operaciones básicas de la tienda](/es/publishing/xstore-commerce/xstore-basic-operations.md)
- [XStore (contenido de la API)](/es/reference/system/xstore/xstore_members.md)
- [XStoreQueryAssociatedProductsAsync](/es/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md)
- [XStoreQueryAssociatedProductsResult](/es/reference/system/xstore/functions/xstorequeryassociatedproductsresult.md)