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

Retourne les informations du Store pour tous les produits liés au jeu en cours auxquels l'utilisateur a droit.

## Syntaxe

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

### Paramètres

*storeContextHandle*   \_In\_\
Type : XStoreContextHandle

Handle de contexte du Store pour l'utilisateur, retourné par [XStoreCreateContext](/fr-CA/reference/system/xstore/functions/xstorecreatecontext).

*productKinds*   \_In\_\
Type : [XStoreProductKind](/fr-CA/reference/system/xstore/enums/xstoreproductkind)

Type de produits à interroger.

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

Nombre maximal d'éléments à récupérer par page.
Le nombre d'éléments retournés par page peut varier de 0 à `maxItemsToRetrievePerPage`.

*async*   \_Inout\_\
Type : [XAsyncBlock\*](/fr-CA/reference/system/xasync/structs/xasyncblock)

[XAsyncBlock](/fr-CA/reference/system/xasync/structs/xasyncblock) définissant le travail asynchrone en cours.
Le [XAsyncBlock](/fr-CA/reference/system/xasync/structs/xasyncblock) peut être utilisé pour interroger l'état de l'appel et récupérer les résultats de l'appel.
Pour plus d'informations, consultez [XAsyncBlock](/fr-CA/reference/system/xasync/structs/xasyncblock).

### Valeur de retour

Type : HRESULT

Retourne S\_OK en cas de réussite; sinon, retourne un code d'erreur.

## Remarques

Appelez [XStoreQueryEntitledProductsResult](/fr-CA/reference/system/xstore/functions/xstorequeryentitledproductsresult) pour récupérer les informations sur les produits du Store et le résultat d'exécution de cette fonction.
Exécutez [XStoreQueryEntitledProductsResult](/fr-CA/reference/system/xstore/functions/xstorequeryentitledproductsresult) dans la fonction de rappel de `XStoreQueryEntitledProductsAsync`.
Le résultat contient un `XStoreProductQueryHandle` que vous pouvez énumérer en appelant [XStoreEnumerateProductsQuery](/fr-CA/reference/system/xstore/functions/xstoreenumerateproductsquery).

<Note>
  Plus un joueur a droit à des éléments, plus le retour de cette API peut être long.

  Cette API prend en charge le même modèle de pagination que celui décrit dans [XStoreQueryAssociatedProductsAsync](/fr-CA/reference/system/xstore/functions/xstorequeryassociatedproductsasync).

  La pagination peut se comporter différemment entre les bacs à sable et RETAIL. Vérifiez votre implémentation de la pagination et assurez-vous de la tester dans RETAIL avant la sortie.

  Pour plus d'informations, consultez [Pagination](/fr-CA/reference/system/xstore/functions/xstorequeryassociatedproductsasync#paging).
</Note>

Vous ne pouvez pas connaître à l'avance le nombre de produits retournés par cette requête.

L'extrait de code suivant fournit un exemple de requête des droits d'un utilisateur sur le contenu lié au jeu en cours.
Les résultats sont traités sur plusieurs pages.

```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);
    }
}

```

## Configuration requise

**En-tête :** XStore.h (inclus dans XGameRuntime.h)

**Bibliothèque :** xgameruntime.lib

**Plateformes prises en charge :** Windows, consoles de la famille XBOX One et consoles XBOX Series

## Documentation conceptuelle

* [Implémenter les achats en jeu dans votre jeu](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/tutorials/pc-e2e-guide/e2e-services/e2e-in-game-purchases)
* [Opérations de base du Store](/fr-CA/publishing/xstore-commerce/xstore-basic-operations)
* [Comment utiliser un durable sans package](/fr-CA/publishing/xstore-commerce/xstore-dwob)
* [Accorder aux joueurs l'accès au contenu des extensions](/fr-CA/publishing/xstore-commerce/xstore-granting-access)
* [Vue d'ensemble des systèmes de commerce du GDK](/fr-CA/publishing/xstore-commerce/xstore-overview)
* [Limitation de débit précise pour les API du Microsoft Store](/fr-CA/publishing/xstore-commerce/xstore-fgrl)

## Voir aussi

[XStore](/fr-CA/reference/system/xstore/xstore_members)\
[XStoreQueryEntitledProductsResult](/fr-CA/reference/system/xstore/functions/xstorequeryentitledproductsresult)
[XStoreQueryAssociatedProductsAsync](/fr-CA/reference/system/xstore/functions/xstorequeryassociatedproductsasync)\
[XStoreQueryEntitledProductsAsync](/fr-CA/reference/system/xstore/functions/xstorequeryentitledproductsasync)\
[XStoreQueryProductsAsync](/fr-CA/reference/system/xstore/functions/xstorequeryproductsasync)\
[XStoreQueryProductForCurrentGameAsync](/fr-CA/reference/system/xstore/functions/xstorequeryproductforcurrentgameasync)\
[XStoreQueryProductForPackageAsync](/fr-CA/reference/system/xstore/functions/xstorequeryproductforpackageasync)\
[Opérations de base du Store](/fr-CA/publishing/xstore-commerce/xstore-basic-operations)\
[Accorder aux joueurs l'accès au contenu des extensions](/fr-CA/publishing/xstore-commerce/xstore-granting-access)


## Related topics

- [XStoreQueryEntitledProductsAsync](/reference/system/xstore/functions/xstorequeryentitledproductsasync.md)
- [XStoreQueryEntitledProductsResult](/reference/system/xstore/functions/xstorequeryentitledproductsresult.md)
- [XStoreQueryProductsAsync](/reference/system/xstore/functions/xstorequeryproductsasync.md)
- [XStoreQueryProductForPackageAsync](/reference/system/xstore/functions/xstorequeryproductforpackageasync.md)
- [XStoreQueryProductsResult](/reference/system/xstore/functions/xstorequeryproductsresult.md)