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

# XStoreQueryAssociatedProductsAsync

> XStoreQueryAssociatedProductsAsync

# XStoreQueryAssociatedProductsAsync

Obtient les informations de fiche du Store pour les produits que les utilisateurs peuvent acheter depuis le jeu en cours.

## Syntaxe

```cpp theme={null}
HRESULT XStoreQueryAssociatedProductsAsync(  
         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/reference/system/xstore/functions/xstorecreatecontext).

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

Type de produits à retourner.

*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`.
Pour plus d'informations, consultez [Pagination](#paging).

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

[XAsyncBlock](/fr/reference/system/xasync/structs/xasyncblock) définissant le travail asynchrone en cours.
Utilisez le [XAsyncBlock](/fr/reference/system/xasync/structs/xasyncblock) pour interroger l'état de l'appel et récupérer ses résultats.
Pour plus d'informations, consultez [XAsyncBlock](/fr/reference/system/xasync/structs/xasyncblock).

### Valeur renvoyée

Type : HRESULT

Code de réussite ou d'erreur HRESULT.

## Remarques

Pour obtenir les informations de fiche du Store et le résultat de l'exécution de cette fonction, appelez [XStoreQueryAssociatedProductsResult](/fr/reference/system/xstore/functions/xstorequeryassociatedproductsresult) après avoir appelé cette fonction.
[XStoreQueryAssociatedProductsResult](/fr/reference/system/xstore/functions/xstorequeryassociatedproductsresult) contient un `XStoreProductQueryHandle` que vous énumérez en appelant [XStoreEnumerateProductsQuery](/fr/reference/system/xstore/functions/xstoreenumerateproductsquery).

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

Cette API retourne uniquement les produits que les utilisateurs peuvent parcourir dans le Microsoft Store ou acheter dans le jeu.
Les résultats n'incluent aucun produit masqué, expiré ou retiré du Store.
Si vous avez besoin des détails d'un tel produit, utilisez [XStoreQueryProductsAsync](/fr/reference/system/xstore/functions/xstorequeryproductsasync) en lui passant le Store ID du produit.

## Pagination

Cette fonction retourne les produits sur plusieurs pages (jusqu'à `maxItemsToRetrievePerPage` éléments par page).
Utilisez [XStoreProductsQueryHasMorePages](/fr/reference/system/xstore/functions/xstoreproductsqueryhasmorepages) et [XStoreProductsQueryNextPageAsync](/fr/reference/system/xstore/functions/xstoreproductsquerynextpageasync)/[XStoreProductsQueryNextPageResult](/fr/reference/system/xstore/functions/xstoreproductsquerynextpageresult) pour traiter tous les résultats paginés.
La pagination n'est terminée que lorsque `XStoreProductsQueryHasMorePages` retourne false.

<Note>
  La pagination peut se comporter différemment dans les sandbox et dans RETAIL.
  Dans une sandbox, les éléments s'accumulent jusqu'à `maxItemsToRetrievePerPage` avant qu'une page soit retournée.
  Dans RETAIL, il est courant que 0 à 1 élément soit retourné par page.

  Il est important que tous les jeux utilisant cette API implémentent et testent la pagination avant leur sortie.

  Pour tester le comportement de la pagination dans une sandbox, définissez temporairement `maxItemsToRetrievePerPage` sur une valeur inférieure au nombre de produits publiés dans votre sandbox.
  Pour tester dans RETAIL avant la sortie de votre jeu, publiez des produits à l'aide de l'option **Enable Private Audience** de la page « Pricing and availability » dans Partner Center.
  Pour tester dans RETAIL après la sortie de votre jeu, utilisez une version d'évaluation de package (package flight).
</Note>

Le code suivant montre comment récupérer les résultats d'une requête de produits sur plusieurs pages.

Veillez à transmettre le handle de requête tout au long de la récursion de pagination afin d'éviter les fuites.

```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 QueryAssociatedProductsCallback(XAsyncBlock* async)
{
    auto* ctx = static_cast<QueryContext*>(async->context);

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

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

    // Check if there are more pages to process
    if (XStoreProductsQueryHasMorePages(ctx->handle))
    {
        QueryNextPage(async);
        return;
    }

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

void QueryAssociatedProducts(XStoreContextHandle storeContextHandle, XTaskQueueHandle taskQueueHandle)
{
    auto async = new XAsyncBlock{};
    async->context = new QueryContext{ 0, nullptr };
    async->queue = taskQueueHandle;
    async->callback = QueryAssociatedProductsCallback;

    XStoreProductKind typeFilter =
        XStoreProductKind::Consumable |
        XStoreProductKind::Durable |
        XStoreProductKind::Game |
        XStoreProductKind::Pass |
        XStoreProductKind::UnmanagedConsumable;

    HRESULT hr = XStoreQueryAssociatedProductsAsync(
        storeContextHandle,
        typeFilter,
        25,          // Products per page (25 is a good default, can set lower to verify paging in sandbox)
        async);

    if (FAILED(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; }

        // Check if there are more pages to process
        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);
    }
}

```

## 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/publishing/xstore-commerce/xstore-basic-operations)
* [Accorder aux joueurs l'accès au contenu des extensions](/fr/publishing/xstore-commerce/xstore-granting-access)
* [Vue d'ensemble des systèmes de commerce du GDK](/fr/publishing/xstore-commerce/xstore-overview)
* [Limitation de débit granulaire pour les API du Microsoft Store](/fr/publishing/xstore-commerce/xstore-fgrl)
* [Outil de droits de développement du Store (DevEntitlementTool.exe)](/fr/tools/tools-services/live-dev-entitlements-tool)

## Voir aussi

[XStore](/fr/reference/system/xstore/xstore_members)\
[XStoreQueryAssociatedProductsResult](/fr/reference/system/xstore/functions/xstorequeryassociatedproductsresult)\
[XStoreEnumerateProductsQuery](/fr/reference/system/xstore/functions/xstoreenumerateproductsquery)\
[XStoreProductsQueryHasMorePages](/fr/reference/system/xstore/functions/xstoreproductsqueryhasmorepages)\
[XStoreProductsQueryNextPageAsync](/fr/reference/system/xstore/functions/xstoreproductsquerynextpageasync)\
[Opérations de base du Store](/fr/publishing/xstore-commerce/xstore-basic-operations)\
[Accorder aux joueurs l'accès au contenu des extensions](/fr/publishing/xstore-commerce/xstore-granting-access)


## Related topics

- [XStoreQueryAssociatedProductsAsync](/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md)
- [XStoreQueryAssociatedProductsResult](/reference/system/xstore/functions/xstorequeryassociatedproductsresult.md)
- [XStoreQueryAssociatedProductsForStoreIdAsync](/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidasync.md)
- [XStoreQueryProductsAsync](/reference/system/xstore/functions/xstorequeryproductsasync.md)
- [XStoreQueryProductForPackageAsync](/reference/system/xstore/functions/xstorequeryproductforpackageasync.md)