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

스토어 ID로 지정된 대상 제품과 관련된 구매 가능한 제품의 스토어 목록 정보를 가져옵니다.

## 구문

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

### 매개 변수

*storeContextHandle*   \_In\_\
형식: XStoreContextHandle

[XStoreCreateContext](/ko/reference/system/xstore/functions/xstorecreatecontext)에서 반환된 사용자의 스토어 컨텍스트 핸들입니다.

*storeId*   \_In\_\
형식: const char\*

연결된 제품을 검색할 제품의 스토어 ID입니다.

*productKinds*   \_In\_\
형식: [XStoreProductKind](/ko/reference/system/xstore/enums/xstoreproductkind)

반환할 제품의 형식입니다.

*maxItemsToRetrievePerPage*   \_In\_\
형식: uint32\_t

페이지당 검색할 최대 항목 수입니다.
페이지당 반환되는 항목 수는 0에서 `maxItemsToRetrievePerPage` 사이일 수 있습니다.

*async*   \_Inout\_\
형식: [XAsyncBlock\*](/ko/reference/system/xasync/structs/xasyncblock)

수행 중인 비동기 작업을 정의하는 [XAsyncBlock](/ko/reference/system/xasync/structs/xasyncblock)입니다.
[XAsyncBlock](/ko/reference/system/xasync/structs/xasyncblock)을 사용하여 호출 상태를 폴링하고 호출 결과를 검색합니다.
자세한 내용은 [XAsyncBlock](/ko/reference/system/xasync/structs/xasyncblock)을 참조하세요.

### 반환 값

형식: HRESULT

HRESULT 성공 또는 오류 코드입니다.

## 설명

이 함수의 스토어 목록 정보 및 실행 결과를 얻으려면 이 함수를 호출한 후 [XStoreQueryAssociatedProductsForStoreIdResult](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult)를 호출하세요.
[XStoreQueryAssociatedProductsForStoreIdResult](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult)에는 [XStoreEnumerateProductsQuery](/ko/reference/system/xstore/functions/xstoreenumerateproductsquery)를 호출하여 열거되는 `XStoreProductQueryHandle`이 포함되어 있습니다.

> [!NOTE]
>
> 이 API는 [XStoreQueryAssociatedProductsAsync](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsasync)에 설명된 것과 동일한 페이징 패턴을 지원합니다.
>
> 페이징은 샌드박스와 RETAIL 간에 다르게 동작할 수 있습니다.
> 페이징 구현을 확인하고 릴리스 전에 RETAIL에서 반드시 테스트하세요.
>
> 자세한 내용은 [페이징](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsasync#paging)을 참조하세요.

이 쿼리가 반환하는 제품의 수는 미리 알 수 없습니다.

이 API를 사용하여 대상 제품의 스토어 ID로 해당 제품과 연결된 추가 기능(add-on)을 찾을 수 있습니다.
이 기능은 Franchise Game Hub에 특히 유용합니다. Franchise Game Hub는 여러 게임에 대한 추가 기능을 열거할 수 있지만, 이러한 추가 기능이 어떤 게임과 연결되어 있는지는 알 수 없습니다.

사용 시나리오 예시:

* 개발자는 `XPackageEnumeratePackages`를 실행하여 설치된 [XPackageKind::Game](/ko/reference/system/xpackage/enums/xpackagekind) 제품을 열거한 다음, 이러한 게임 중 하나에 대해 `XPackageDetails`에서 가져온 storeId를 사용하여 `XStoreQueryAssociatedProductsForStoreIdAsync`를 실행합니다. 개발자는 [XPackageKind::Content](/ko/reference/system/xpackage/enums/xpackagekind)에 대해 `XPackageEnumeratePackages`를 실행하여 설치된 DLC를 열거합니다. 콘텐츠 열거 및 제품 쿼리의 결과가 상호 참조되어 특정 게임에 어떤 DLC가 설치되어 있는지 식별할 수 있습니다.

* 개발자는 `XStoreQueryAssociatedProductsAsync`를 실행하여 현재 게임과 연결된 구매 가능한 제품 목록을 가져옵니다. 그런 다음 대상 게임의 `XStoreProduct`의 storeId를 사용하여 `XStoreQueryAssociatedProductsForStoreIdAsync`를 실행하여 어떤 DLC가 연결되어 있는지 확인합니다.

다음 코드 조각은 스토어 ID를 사용하여 대상 제품과 연결된 제품을 쿼리하는 예를 보여줍니다.
결과는 여러 페이지에 걸쳐 처리됩니다.

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

```

## 요구 사항

**헤더:** XStore.h (XGameRuntime.h에 포함됨)

**라이브러리:** xgameruntime.lib

**지원 플랫폼:** Windows, XBOX One 제품군 콘솔 및 XBOX Series 콘솔

## 개념 설명서

* [기본 스토어 작업](/ko/publishing/xstore-commerce/xstore-basic-operations)

## 참고 항목

[XStore](/ko/reference/system/xstore/xstore_members)\
[XStoreQueryAssociatedProductsForStoreIdResult](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult)\
[XStoreQueryAssociatedProductsAsync](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsasync)\
[XStoreEnumerateProductsQuery](/ko/reference/system/xstore/functions/xstoreenumerateproductsquery)\
[XStoreProductsQueryHasMorePages](/ko/reference/system/xstore/functions/xstoreproductsqueryhasmorepages)\
[XStoreProductsQueryNextPageAsync](/ko/reference/system/xstore/functions/xstoreproductsquerynextpageasync)


## Related topics

- [XStoreQueryAssociatedProductsForStoreIdResult](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult.md)
- [기본 스토어 작업](/ko/publishing/xstore-commerce/xstore-basic-operations.md)
- [XStore (API 콘텐츠)](/ko/reference/system/xstore/xstore_members.md)
- [XStoreQueryAssociatedProductsAsync](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsasync.md)
- [XStoreQueryAssociatedProductsResult](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsresult.md)