XStoreQueryEntitledProductsAsync

사용자에게 권한이 있는 현재 게임과 관련된 모든 추가 콘텐츠, DLC 및 소모품에 대한 Microsoft Store 제품 정보를 제공합니다.

구문

HRESULT XStoreQueryEntitledProductsAsync(  
         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

성공하면 S_OK를 반환하고, 그렇지 않으면 오류 코드를 반환합니다.

비고

Microsoft Store 제품 정보와 이 함수의 실행 결과를 함께 검색하려면, 이 함수 호출 후 XStoreQueryEntitledProductsResult를 호출합니다. XStoreQueryEntitledProductsResult는 XStoreQueryEntitledProductsAsync의 콜백 함수에서 실행해야 합니다.

Important

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

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

다음 코드 조각은 사용자가 현재 게임의 관련 콘텐츠에 대한 사용자 권한을 기반으로 Microsoft Store 제품 정보를 검색하는 예를 보여줍니다.

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

    HRESULT hr = XStoreQueryEntitledProductsResult(
        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);
    //Perform desired operations using the results. Make sure to check for more pages.
}

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

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

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

    if (FAILED(hr))
    {
        printf("Failed to get user collection: 0x%x\r\n", hr);
        return;
    }
    
    if(FAILED(XAsyncGetStatus(asyncBlock, true))) 
    { 
        printf("XStoreQueryEntitledProductsAsync failed\r\n"); 
        return; 
    } 
}

요구 사항

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

라이브러리: xgameruntime.lib

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

참고 항목

XStore
XStoreQueryEntitledProductsResultXStoreQueryAssociatedProductsAsync
XStoreQueryEntitledProductsAsync
XStoreQueryProductsAsync
XStoreQueryProductForCurrentGameAsync
XStoreQueryProductForPackageAsync