XPackageCreateInstallationMonitor
설치 상태에 대한 모니터를 만듭니다.
구문
HRESULT XPackageCreateInstallationMonitor(
const char* packageIdentifier,
uint32_t selectorCount,
XPackageChunkSelector* selectors,
uint32_t minimumUpdateIntervalMs,
XTaskQueueHandle queue,
XPackageInstallationMonitorHandle* installationMonitor
)
매개 변수
packageIdentifier _In_z_
형식: char*
디스크에 설치된 패키지를 고유하게 식별하는 문자열입니다. 패키지 식별자에 대한 자세한 내용은 DLC(다운로드 가능한 콘텐츠 관리 및 라이선스)를참조하세요.
selectorCount _In_
형식: uint32_t
selectors 매개 변수의 선택기 수입니다.
selectors _In_reads_opt_(selectorCount)
형식: XPackageChunkSelector*
모니터링할 청크를 지정하는 선택기 배열입니다.
minimumUpdateIntervalMs _In_
형식: uint32_t
모니터의 해상도(밀리초)입니다.
queue _In_opt_
형식: XTaskQueueHandle
업데이트가 수행되는 큐입니다.
installationMonitor _Out_
형식: XPackageInstallationMonitorHandle*
반환 시, 생성된 설치 모니터를 가리킵니다.
반환 값
형식: HRESULT
HRESULT 성공 또는 오류 코드입니다.
설명
참고 항목
이 함수는 시간에 민감한 스레드에서 호출하는 것이 안전하지 않습니다. 자세한 내용은 시간에 민감한 스레드를 참조하세요.
XPackageCreateInstallationMonitor는 설치 상태를 추적하는 모니터를 만듭니다. 모니터는 지정된 업데이트 간격에 따라 결정되는 정기적인 케이던스로 업데이트되고 새로 고쳐집니다. 지정된 작업 큐에서 업데이트가 예약됩니다. 간격이 0이면 업데이트를 수행하지 않도록 지정하고 일회성 설치 스냅숏인 설치 모니터를 만듭니다. 간격이 0으로 전달되면 큐 매개 변수는 null이 될 수 있습니다.
현재 설치 진행 상황을 가져오려면 XPackageGetInstallationProgress를 호출하고, 설치 중 변경 내용에 대한 알림을 받으려면 콜백을 등록합니다. 이 설치 모니터는 전체 패키지 또는 특정 하위 집합에 대해 만들 수 있습니다.
게임이 시작 마커를 구현했으므로 완전히 설치되기 전에 실행할 수 있습니다. 게임은 설치된 부분과 설치되지 않은 부분을 파악해야 합니다. 이 예제에서 게임은 지정된 트랙 이름을 가진 트랙에 연결된 청크가 설치되는 시점을 알고 있어야 합니다.
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);
설치된 모든 콘텐츠에는 고유 식별자가 있습니다. 패키지의 식별자를 알고 있고 해당 콘텐츠에 대한 액세스 권한이 있는 경우 모든 패키지의 설치를 모니터링할 수 있습니다. 실행 중인 프로세스는 자체 패키지 식별자를 가져올 수 있습니다.
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 콘솔