XStoreQueryAssociatedProductsAsync

현재 게임에서 구입할 수 있는 제품에 대한 Microsoft Store 목록 정보를 가져옵니다.

구문

HRESULT XStoreQueryAssociatedProductsAsync(  
         const XStoreContextHandle storeContextHandle,  
         XStoreProductKind productKinds,  
         uint32_t maxItemsToRetrievePerPage,  
         XAsyncBlock* async  
)  

매개 변수

storeContextHandle _In_
형식: XStoreContextHandle

XStoreCreateContext가 반환하는 사용자의 Microsoft Store 컨텍스트 핸들입니다.

productKinds _In_
형식: XStoreProductKind

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

maxItemsToRetrievePerPage _In_
형식: uint32_t

페이지당 검색할 최대 항목 수입니다. 페이지당 25개 이상의 항목을 전달하면 여러 서비스 왕복이 각 페이지에 대해 필요하게 됩니다.

async _Inout_
형식: XAsyncBlock*

수행할 비동기 작업을 정의하는 XAsyncBlock입니다. 호출의 상태를 폴링하고 호출 결과를 검색하기 위해 사용할 수 있는 XAsyncBlock입니다. 자세한 내용은 XAsyncBlock을 참조하세요.

반환 값

형식: HRESULT

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

비고

Store 목록 정보와 이 함수의 실행 결과를 함께 검색하려면, 이 함수 호출 후 XStoreQueryAssociatedProductsResult를 호출합니다. XStoreQueryAssociatedProductsResult에는 XStoreEnumerateProductsQuery를 호출하여 열거할 XStoreProductQueryHandle이 있습니다.

Important

결과 수가 maxItemsToRetrievePerPage보다 작은 경우에도 여러 페이지에 제품 쿼리가 반환될 수 있습니다. 반드시 추가 제품 항목을 확인하고 XStoreProductsQueryHasMorePages 및 XStoreProductsQueryNextPageAsync를 각각 호출하여 읽어야 합니다.

이 쿼리에서 미리 반환할 제품 수를 알 수 있는 방법은 없습니다.

이 API는 Microsoft Store 내에서 검색할 수 있는 제품과 스토어 페이지가 없는 추가 기능 제품(만료되지 않은 경우)만 반환합니다. Microsoft Store에서 숨겨지거나 만료되었거나 내려진 제품은 이 API의 결과에 반환되지 않습니다. 이러한 제품의 저장소 정보가 필요한 경우 제품의 StoreID에 전달되는 XStoreQueryProductsAsync를 사용합니다.

다음 코드 조각은 현재 게임에서 구입할 수 있는 제품에 대한 Microsoft Store 목록 정보를 검색하는 예를 보여줍니다.

bool CALLBACK EnumerateProductsQueryCallback(const XStoreProduct* product, void* context)
{
    printf("Product:\r\n");
    printf("\tstoreId    : %s\r\n", product->storeId);
    printf("\tproductKind: %s\r\n", product->productKind);

    // Return true to keep enumerating, false to stop
    return true;
}

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

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

    bool hasMorePages = XStoreProductsQueryHasMorePages(queryHandle);
    if (hasMorePages)
    {
        auto asyncInner = std::make_unique<XAsyncBlock>();
        ZeroMemory(asyncInner.get(), sizeof(*asyncInner));
        asyncInner->queue = taskQueueHandle;
        asyncInner->callback = ProductsQueryNextPageCallback;

        hr = XStoreProductsQueryNextPageAsync(
            queryHandle,
            asyncInner.get());

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

    XStoreCloseProductsQueryHandle(queryHandle);
}

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

    HRESULT hr = XStoreQueryAssociatedProductsResult(
        asyncBlock,
        &queryHandle);

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

    XTaskQueueHandle taskQueueHandle = reinterpret_cast<XTaskQueueHandle>(asyncBlock->context);
    ProcessResults(queryHandle, taskQueueHandle);
}

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

    HRESULT hr = XStoreProductsQueryNextPageResult(
        asyncBlock,
        &queryHandle);

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

    XTaskQueueHandle taskQueueHandle = reinterpret_cast<XTaskQueueHandle>(asyncBlock->context);
    ProcessResults(queryHandle, taskQueueHandle);
}

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

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

    HRESULT hr = XStoreQueryAssociatedProductsAsync(
        storeContextHandle,
        allProductKinds,
        25,     // Max items per page
        asyncBlock.get());

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

    // Wait a while for the callbacks to run
    Sleep(5000);
}

요구 사항

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

라이브러리: xgameruntime.lib

지원되는 플랫폼: Windows, Xbox One 패밀리 콘솔 및 Xbox Series 콘솔

참고 항목

XStore
XStoreQueryAssociatedProductsResult
XStoreEnumerateProductsQuery
XStoreProductsQueryHasMorePages
XStoreProductsQueryNextPageAsync