XPackageGetInstallationProgress

설치 현재 진행 상태를 반환합니다.

구문

void XPackageGetInstallationProgress(  
         XPackageInstallationMonitorHandle installationMonitor,  
         XPackageInstallationProgress* progress  
)  

매개 변수

installationMonitor _In_
형식: XPackageInstallationMonitorHandle

설치 모니터에 대한 핸들입니다.

progress _Out_
형식: XPackageInstallationProgress*

반환 시, 설치 현재 진행 상태를 포함합니다.

반환 값

형식: void

비고

현재 설치 진행 상황을 가져오려면 XPackageGetInstallationProgress를 호출하고, 설치 중 변경 내용에 대한 알림을 받으려면 콜백을 등록합니다. 전체 패키지 또는 특정 하위 집합에 대한 설치 모니터를 만들 수 있습니다.

새 콘텐츠를 새로 설치하는 잠시 동안 설치가 완전히 시작되지 않았기 때문에 런타임에서 패키지의 전체 크기를 계산할 수 없습니다. 이 경우 런타임에서는 UINT64_MAX를 totalBytes의 값으로 반환하고 다른 모든 필드의 경우 0 또는 false를 반환할 것입니다.

예제:

void CALLBACK ProgressChangedCallback(
    void* /* context*/,
    XPackageInstallationMonitorHandle monitor)
{
    XPackageInstallationProgress progress;
    XPackageGetInstallationProgress(monitor, &progress);

    if (progress.completed)
    {
        printf("Track ready\n");
        XPackageCloseInstallationMonitorHandle(monitor);
    }
}

HRESULT StartMonitoring(XTaskQueueHandle queue, char* trackName)
{
    char id[XPACKAGE_IDENTIFIER_MAX_LENGTH];

    HRESULT hr = XPackageGetCurrentProcessPackageIdentifier(_countof(id), id);
    if (FAILED(hr)) return hr;

    XPackageChunkSelector selector;
    selector.type = XPackageChunkSelectorType::Tag;
    selector.tag = trackName;

    XPackageInstallationMonitorHandle monitor;
    hr = XPackageCreateInstallationMonitor(
        id,         // Identity to be monitored
        1,          // Number of selectors
        &selector,  // Selectors
        1000,       // Resolution of the monitor, in milliseconds
        queue,      // Queue where updates are performed
        &monitor);
    if (FAILED(hr)) return hr;

    XTaskQueueRegistrationToken token;
    hr = XPackageRegisterInstallationProgressChanged(
        monitor,
        nullptr,
        ProgressChangedCallback,
        &token);

    if (FAILED(hr))
    {
        XPackageCloseInstallationMonitorHandle(monitor);
    }

    return hr;
}

위에 표시된 코드에서 각 API 호출을 살펴보겠습니다.

XPackageGetCurrentProcessPackageIdentifier(_countof(id), id); 

설치된 모든 콘텐츠에는 고유 식별자가 있습니다. 패키지의 식별자를 알고 있고 해당 콘텐츠에 대한 액세스 권한이 있는 경우 모든 패키지의 설치를 모니터링할 수 있습니다. 실행 중인 프로세스는 자체 패키지 식별자를 가져올 수 있습니다. 패키지 식별자에 대한 자세한 내용은 DLC(다운로드 가능한 콘텐츠 관리 및 라이선스)를참조하세요.

XPackageCreateInstallationMonitor( 
    id,         // Identity to be monitored 
    1,          // Number of selectors 
    &selector,  // Selectors 
    1000,       // Resolution of the monitor, in milliseconds 
    queue,      // Queue where updates are performed 
    &monitor); 

이렇게 하면 설치 상태를 추적하는 모니터가 만들어집니다. 이 설치 모니터는 일반 케이던스로 자체적으로 업데이트됩니다. 현재 설치 진행 상황을 가져오려면 XPackageGetInstallationProgress를 호출하고, 설치 중 변경 내용에 대한 알림을 받으려면 콜백을 등록합니다.

전체 패키지 또는 특정 하위 집합에 대한 설치 모니터를 만들 수 있습니다. 여기에서 트랙 이름의 설치 진행 상황을 알고 싶다는 "selector"를 정의했습니다. 설치 모니터가 진행률 스냅숏을 업데이트하는 빈도(이 경우 1000 밀리초)를 이 속도까지 지정할 수 있습니다. 시간 내에 진행되지 않은 경우 속도가 더 느려질 수 있습니다.

hr = XPackageRegisterInstallationProgressChanged(
    monitor,
    nullptr,
    ProgressChangedCallback,
    &token);

트랙 로드가 완료된 시점을 알아야 하므로 모니터에 진행률 변경 이벤트를 등록합니다. 이 콜백은 모니터가 만들어질 때 제공된 작업 큐를 통해 XPackageCreateInstallationMonitor에 지정된 케이던스에서 호출됩니다. 콜백 내에서 게임 진행 상태를 렌더링하거나 트랙이 준비되었음을 게임에 알릴 수 있습니다.

이 예제에서는 설치 모니터를 닫지만 알림을 등록 취소하지는 않습니다. 설치 모니터 알림의 수명은 설치 모니터와 연관되어 있습니다. 따라서 모니터를 닫으면 모든 알림이 등록 취소됩니다.

요구 사항

헤더: XPackage.h

라이브러리: xgameruntime.lib

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

참고 항목

XPackage