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

Obtient les informations de fiche du Store pour les produits achetables liés à un produit cible spécifié par son Store ID.

## Syntaxe

```cpp theme={null}
HRESULT XStoreQueryAssociatedProductsForStoreIdAsync(   
         const XStoreContextHandle storeContextHandle,   
         const char* storeId, 
         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).

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

Store ID du produit pour lequel les produits associés sont récupérés.

*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`.

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

[XAsyncBlock](/fr/reference/system/xasync/structs/xasyncblock) qui définit 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 [XStoreQueryAssociatedProductsForStoreIdResult](/fr/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult) après avoir appelé cette fonction.
[XStoreQueryAssociatedProductsForStoreIdResult](/fr/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult) contient un `XStoreProductQueryHandle` qui s'énumère en appelant [XStoreEnumerateProductsQuery](/fr/reference/system/xstore/functions/xstoreenumerateproductsquery).

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

  La pagination peut se comporter différemment dans les sandbox et dans RETAIL.
  Vérifiez votre implémentation de la pagination et veillez à la tester dans RETAIL avant la sortie.

  Pour plus d'informations, consultez [Pagination](/fr/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.

Utilisez cette API pour trouver les extensions associées à un produit cible à l'aide de son Store ID.
Cette capacité est particulièrement utile pour les hubs de jeux de franchise. Un hub de jeux de franchise peut énumérer les extensions de plusieurs jeux, mais il ne peut pas savoir à quel jeu ces extensions sont associées.

Exemples de scénarios d'utilisation :

* Les développeurs exécutent `XPackageEnumeratePackages` pour énumérer les produits [XPackageKind::Game](/fr/reference/system/xpackage/enums/xpackagekind) installés, puis, pour l'un de ces jeux, ils exécutent `XStoreQueryAssociatedProductsForStoreIdAsync` à l'aide du storeId obtenu à partir de `XPackageDetails`. Les développeurs exécutent `XPackageEnumeratePackages` pour [XPackageKind::Content](/fr/reference/system/xpackage/enums/xpackagekind) afin d'énumérer les DLC installés. Les résultats de l'énumération du contenu et de la requête de produits sont recoupés, ce qui permet aux développeurs d'identifier les DLC installés pour ce jeu spécifique.

* Les développeurs exécutent `XStoreQueryAssociatedProductsAsync` pour obtenir la liste des produits achetables associés au jeu en cours. Ensuite, à l'aide du storeId provenant du `XStoreProduct` du jeu cible, ils exécutent `XStoreQueryAssociatedProductsForStoreIdAsync` pour déterminer quels DLC lui sont associés.

L'extrait de code suivant montre un exemple de requête des produits associés à un produit cible à l'aide de son Store ID.
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 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);
    }
}

```

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

* [Opérations de base du Store](/fr/publishing/xstore-commerce/xstore-basic-operations)

## Voir aussi

[XStore](/fr/reference/system/xstore/xstore_members)\
[XStoreQueryAssociatedProductsForStoreIdResult](/fr/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult)\
[XStoreQueryAssociatedProductsAsync](/fr/reference/system/xstore/functions/xstorequeryassociatedproductsasync)\
[XStoreEnumerateProductsQuery](/fr/reference/system/xstore/functions/xstoreenumerateproductsquery)\
[XStoreProductsQueryHasMorePages](/fr/reference/system/xstore/functions/xstoreproductsqueryhasmorepages)\
[XStoreProductsQueryNextPageAsync](/fr/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)