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

## 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-CA/reference/system/xstore/functions/xstorecreatecontext).

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

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

*productKinds*   \_In\_\
Type : [XStoreProductKind](/fr-CA/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-CA/reference/system/xasync/structs/xasyncblock)

[XAsyncBlock](/fr-CA/reference/system/xasync/structs/xasyncblock) qui définit le travail asynchrone en cours.
Utilisez le [XAsyncBlock](/fr-CA/reference/system/xasync/structs/xasyncblock) 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

Code de réussite ou d'erreur HRESULT.

## Remarques

Pour obtenir les informations de fiche du Store et le résultat d'exécution de cette fonction, appelez [XStoreQueryAssociatedProductsForStoreIdResult](/fr-CA/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult) après avoir appelé cette fonction.
[XStoreQueryAssociatedProductsForStoreIdResult](/fr-CA/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult) contient un `XStoreProductQueryHandle` qui est énuméré en appelant [XStoreEnumerateProductsQuery](/fr-CA/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-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 que cette requête retourne.

Utilisez l'API pour trouver les extensions associées à un produit cible à l'aide de son ID Store.
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 déterminer à 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-CA/reference/system/xpackage/enums/xpackagekind) installés, puis, pour l'un de ces jeux, ils exécutent `XStoreQueryAssociatedProductsForStoreIdAsync` en utilisant le storeId obtenu à partir des `XPackageDetails`. Les développeurs exécutent `XPackageEnumeratePackages` pour [XPackageKind::Content](/fr-CA/reference/system/xpackage/enums/xpackagekind) afin d'énumérer le contenu téléchargeable (DLC) installé. 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 quels DLC sont installés pour le jeu en question.

* Les développeurs exécutent `XStoreQueryAssociatedProductsAsync` pour obtenir la liste des produits achetables associés au jeu en cours. Ensuite, en utilisant le storeId du `XStoreProduct` du jeu cible, les développeurs exécutent `XStoreQueryAssociatedProductsForStoreIdAsync` pour déterminer quels DLC lui sont associés.

L'extrait de code suivant montre un exemple de requête de produits associés à un produit cible à l'aide de son ID Store.
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-CA/publishing/xstore-commerce/xstore-basic-operations)

## Voir aussi

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