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

# XStoreQueryProductsAsync

> XStoreQueryProductsAsync

# XStoreQueryProductsAsync

현재 게임과 연결된 지정된 제품에 대한 스토어 목록 정보를 반환합니다. 해당 제품이 게임 내에서 구매 가능한지 여부에 관계없이 반환합니다.

## 구문

```cpp theme={null}
HRESULT XStoreQueryProductsAsync(  
         const XStoreContextHandle storeContextHandle,  
         XStoreProductKind productKinds,  
         const char** storeIds,  
         size_t storeIdsCount,  
         const char** actionFilters,  
         size_t actionFiltersCount,  
         XAsyncBlock* async  
)  
```

### 매개 변수

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

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

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

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

*storeIds*   \_In\_z\_count\_(storeIdsCount)\
형식: char\*\*

검색할 제품의 스토어 식별자입니다.

*storeIdsCount*   \_In\_\
형식: size\_t

**storeIds** 목록에 있는 제품의 수입니다.
이 값은 100을 초과할 수 없습니다.

*actionFilters*   \_In\_opt\_z\_count\_(actionFiltersCount)\
형식: char\*\*

제품 문서에 저장된 특정 액션으로 결과를 제한합니다.
기본적으로 이 API는 구매할 수 없는 제품이라도 모든 제품을 반환하지만, 액션 필터를 사용하여 결과를 제한할 수 있습니다.
예를 들어 구매 가능한 제품만 원하는 경우 "Purchase"를 사용하거나 라이선스 가능한 제품만 원하는 경우 "License"를 사용합니다.
다른 액션 필터에는 "Fulfill", "Browse", "Curate", "Details", "Redeem"이 있습니다.

*actionFiltersCount*   \_In\_\
형식: size\_t

**actionFilters**의 필터 수입니다.

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

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

### 반환 값

형식: HRESULT

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

## 설명

이 함수의 실행 결과와 목록 정보를 검색하려면 [XStoreQueryProductsResult](/reference/system/xstore/functions/xstorequeryproductsresult)를 호출합니다.

요청에서 100개를 초과하는 storeID를 제공하면 이 API는 실패합니다.
큰 카탈로그를 다루는 경우 각 쿼리를 100개 미만의 제품으로 제한하세요.

현재 게임 내에서 플레이어가 구매할 수 있는 모든 제품의 세부 정보를 가져오려면 [XStoreQueryAssociatedProductsAsync](/reference/system/xstore/functions/xstorequeryassociatedproductsasync)를 대신 사용합니다.

다음 코드 조각은 현재 게임과 연결된 지정된 제품에 대한 목록 정보를 검색하는 예를 보여줍니다.

```cpp theme={null}

void ProcessResults(XStoreProductQueryHandle queryHandle)
{
    HRESULT hr = XStoreEnumerateProductsQuery(
        queryHandle,
        nullptr,
        EnumerateProductsQueryCallback);

    if (FAILED(hr))
    {
        printf("Failed enumerate the product query handle: 0x%x\r\n", hr);
        XStoreCloseProductsQueryHandle(queryHandle);
        return;
    }

    XStoreCloseProductsQueryHandle(queryHandle);
}

void CALLBACK QueryProductsCallback(XAsyncBlock* asyncBlock)
{
    XStoreProductQueryHandle queryHandle = nullptr;

    HRESULT hr = XStoreQueryProductsResult(
        asyncBlock,
        &queryHandle);

    if (FAILED(hr))
    {
        printf("Failed retrieve the product query handle: 0x%x\r\n", hr);
        return;
    }

     ProcessResults(queryHandle);
}

void QueryProducts(XStoreContextHandle storeContextHandle, XTaskQueueHandle taskQueueHandle)
{
    auto asyncBlock = std::make_unique<XAsyncBlock>();
    ZeroMemory(asyncBlock.get(), sizeof(*asyncBlock));
    asyncBlock->queue = taskQueueHandle;

    asyncBlock->callback = QueryProductsCallback;

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

    const char* storeIds[] =
    {
        "9YYYYYYYYYYY",
        "9ZZZZZZZZZZZ",
    };

    // This is only needed if you want to restrict to items that are currently purchasable.
    // If you want items that have been sold in the past,
    // but are no longer available for purchase, then
    // pass in nullptr or an empty array for the actionFilters.
    const char* actionFilters[] =
    {
        "Purchase"
    };

    HRESULT hr = XStoreQueryProductsAsync(
        storeContextHandle,
        allProductKinds,
        storeIds,
        ARRAYSIZE(storeIds),
        actionFilters,
        ARRAYSIZE(actionFilters),
        asyncBlock.get());

    if (FAILED(hr))
    {
        printf("Failed to get products: 0x%x\r\n", hr);
        return;
    }
}

```

## 요구 사항

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

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

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

## 개념 설명서

* [기본 스토어 작업](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-basic-store-operations)
* [플레이어에게 추가 기능 콘텐츠에 대한 액세스 권한 부여](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-granting-access-to-content)
* [Microsoft Store API의 세분화된 속도 제한](/publishing/xstore-commerce/xstore-fgrl)

## 참고 항목

[XStore](/reference/system/xstore/xstore_members)
[XStoreQueryProductsResult](/reference/system/xstore/functions/xstorequeryproductsresult)\
[XStoreQueryAssociatedProductsAsync](/reference/system/xstore/functions/xstorequeryassociatedproductsasync)\
[XStoreQueryEntitledProductsAsync](/reference/system/xstore/functions/xstorequeryentitledproductsasync)\
[XStoreQueryProductsAsync](/reference/system/xstore/functions/xstorequeryproductsasync)\
[XStoreQueryProductForCurrentGameAsync](/reference/system/xstore/functions/xstorequeryproductforcurrentgameasync)\
[XStoreQueryProductForPackageAsync](/reference/system/xstore/functions/xstorequeryproductforpackageasync)\
[기본 스토어 작업](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-basic-store-operations)\
[플레이어에게 추가 기능 콘텐츠에 대한 액세스 권한 부여](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-granting-access-to-content)


## Related topics

- [XStoreQueryProductsResult](/ko/reference/system/xstore/functions/xstorequeryproductsresult.md)
- [XStoreQueryProductForPackageAsync](/ko/reference/system/xstore/functions/xstorequeryproductforpackageasync.md)
- [XStoreQueryProductForPackageResult](/ko/reference/system/xstore/functions/xstorequeryproductforpackageresult.md)
- [XStoreQueryProductForCurrentGameAsync](/ko/reference/system/xstore/functions/xstorequeryproductforcurrentgameasync.md)
- [XStoreQueryAssociatedProductsForStoreIdResult](/ko/reference/system/xstore/functions/xstorequeryassociatedproductsforstoreidresult.md)