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

# XStoreQueryEntitledProductsAsync

> XStoreQueryEntitledProductsAsync

# XStoreQueryEntitledProductsAsync

Devuelve información de la tienda de todos los productos relacionados con el juego actual a los que el usuario tiene derecho.

## Sintaxis

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

### Parámetros

*storeContextHandle*   \_In\_\
Tipo: XStoreContextHandle

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

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

El tipo de productos que se van a consultar.

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

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

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

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

### Valor devuelto

Tipo: HRESULT

S\_OK si se realiza correctamente; de lo contrario, devuelve un código de error.

## Comentarios

Llame a [XStoreQueryEntitledProductsResult](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryentitledproductsresult.md) para recuperar la información de producto de la tienda y el resultado de la ejecución de esta función.
Ejecute [XStoreQueryEntitledProductsResult](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryentitledproductsresult.md) en la función de devolución de llamada de `XStoreQueryEntitledProductsAsync`.
El resultado contiene un `XStoreProductQueryHandle` que puede enumerar llamando a [XStoreEnumerateProductsQuery](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstoreenumerateproductsquery.md).

> [!NOTE]
>
> Cuantos más elementos tenga derecho a usar un jugador, más tiempo puede tardar esta API en devolver los resultados.
>
> Esta API admite el mismo patrón de paginación que se describe en [XStoreQueryAssociatedProductsAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md).
>
> La paginación puede comportarse de forma diferente entre los sandbox y RETAIL. Compruebe su implementación de paginación y asegúrese de probarla en RETAIL antes del lanzamiento.
>
> Para obtener más información, consulte [Paginación](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md#paging).

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

El siguiente fragmento de código proporciona un ejemplo de cómo consultar los derechos de un usuario sobre contenido relacionado con el juego actual.
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 QueryEntitledProductsCallback(XAsyncBlock* async)
{
    auto* ctx = static_cast<QueryContext*>(async->context);

    HRESULT hr = XStoreQueryEntitledProductsResult(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 entitled products found\n", ctx->count);
    CleanupProductQuery(async);
}

void QueryEntitledProducts(XStoreContextHandle storeContextHandle, XTaskQueueHandle taskQueueHandle)
{
    auto async = new XAsyncBlock{};
    async->context = new QueryContext{ 0, nullptr };
    async->queue = taskQueueHandle; 
    async->callback = QueryEntitledProductsCallback; 
 
    XStoreProductKind typeFilter = 
        XStoreProductKind::Consumable | 
        XStoreProductKind::Durable | 
        XStoreProductKind::Game |
        XStoreProductKind::Pass |
        XStoreProductKind::UnmanagedConsumable;
 
    HRESULT hr = XStoreQueryEntitledProductsAsync( 
        storeContextHandle, 
        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 entitled products: 0x%x\r\n", 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 entitled 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

* [Implementación de compras en el juego](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/tutorials/pc-e2e-guide/e2e-services/e2e-in-game-purchases)
* [Operaciones básicas de la tienda](https://devdocs.xbox.com/es/publishing/xstore-commerce/xstore-basic-operations.md)
* [Cómo usar un duradero sin paquete](https://devdocs.xbox.com/es/publishing/xstore-commerce/xstore-dwob.md)
* [Concesión a los jugadores de acceso a contenido de complementos](https://devdocs.xbox.com/es/publishing/xstore-commerce/xstore-granting-access.md)
* [Información general de los sistemas de comercio del GDK](https://devdocs.xbox.com/es/publishing/xstore-commerce/xstore-overview.md)
* [Limitación de velocidad específica para las API de Microsoft Store](https://devdocs.xbox.com/es/publishing/xstore-commerce/xstore-fgrl.md)

## Consulte también

[XStore](https://devdocs.xbox.com/es/reference/system/xstore/xstore_members.md)\
[XStoreQueryEntitledProductsResult](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryentitledproductsresult.md)
[XStoreQueryAssociatedProductsAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md)\
[XStoreQueryEntitledProductsAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryentitledproductsasync.md)\
[XStoreQueryProductsAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryproductsasync.md)\
[XStoreQueryProductForCurrentGameAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryproductforcurrentgameasync.md)\
[XStoreQueryProductForPackageAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryproductforpackageasync.md)\
[Operaciones básicas de la tienda](https://devdocs.xbox.com/es/publishing/xstore-commerce/xstore-basic-operations.md)\
[Concesión a los jugadores de acceso a contenido de complementos](https://devdocs.xbox.com/es/publishing/xstore-commerce/xstore-granting-access.md)


## Related topics

- [XStoreQueryEntitledProductsResult](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryentitledproductsresult.md)
- [XStoreQueryProductsAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryproductsasync.md)
- [XStoreQueryProductForPackageAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryproductforpackageasync.md)
- [XStoreQueryProductForPackageResult](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryproductforpackageresult.md)
- [XStoreQueryProductForCurrentGameAsync](https://devdocs.xbox.com/es/reference/system/xstore/functions/xstorequeryproductforcurrentgameasync.md)