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

# XPackageRegisterInstallationProgressChanged

> XPackageRegisterInstallationProgressChanged

# XPackageRegisterInstallationProgressChanged

설치 진행률이 변경될 때 호출할 콜백을 등록합니다.

## 구문

```cpp theme={null}
HRESULT XPackageRegisterInstallationProgressChanged(  
         XPackageInstallationMonitorHandle installationMonitor,  
         void* context,  
         XPackageInstallationProgressCallback* callback,  
         XTaskQueueRegistrationToken* token  
)  
```

### 매개 변수

*installationMonitor*   \_In\_\
형식: XPackageInstallationMonitorHandle

콜백을 등록할 설치 모니터에 대한 핸들입니다.

*context*   \_In\_opt\_\
형식: void\*

콜백에 전달할 컨텍스트입니다.

*callback*   \_In\_\
형식: XPackageInstallationProgressCallback\*

설치 진행률이 변경될 때 호출할 사용자 정의 콜백입니다.

*token*   \_Out\_\
형식: [XTaskQueueRegistrationToken\*](/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken)

콜백을 식별하는 토큰으로, 나중에 [XPackageUnregisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageunregisterinstallationprogresschanged)를 사용하여 콜백을 등록 취소하는 데 사용할 수 있습니다.

### 반환 값

형식: HRESULT

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

## 설명

게임이 완전히 설치되기 전에 실행될 수 있도록 실행 마커를 구현했습니다. 게임은 어떤 부분이 설치되었고 어떤 부분이 설치되지 않았는지 알아야 합니다. 이 예제에서 게임은 지정된 트랙 이름의 레이스트랙과 연결된 청크가 언제 설치되는지 알아야 합니다.

```cpp theme={null}
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,         // 모니터링할 ID
        1,          // 선택자 수
        &selector,  // 선택자
        1000,       // 모니터의 해상도(밀리초)
        queue,      // 업데이트가 수행되는 큐
        &monitor);
    if (FAILED(hr)) return hr;

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

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

    return hr;
}
```

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

```cpp theme={null}
XPackageGetCurrentProcessPackageIdentifier(_countof(id), id);
```

설치된 모든 콘텐츠에는 고유 식별자가 있습니다. 패키지 식별자를 알고 있고 해당 콘텐츠에 액세스할 수 있는 경우 어떤 패키지의 설치든 모니터링할 수 있습니다. 실행 중인 프로세스는 자체 패키지 식별자를 가져올 수 있습니다. 패키지 식별자에 대한 자세한 내용은 [다운로드 가능한 콘텐츠(DLC) 관리 및 라이선스](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-manage-and-license-optional-packages)를 참조하세요.

```cpp theme={null}
XPackageCreateInstallationMonitor(
    id,         // 모니터링할 ID
    1,          // 선택자 수
    &selector,  // 선택자
    1000,       // 모니터의 해상도(밀리초)
    queue,      // 업데이트가 수행되는 큐
    &monitor);
```

이것은 설치 상태를 추적하는 모니터를 만듭니다. 이 설치 모니터는 정기적인 주기로 스스로 업데이트됩니다. 설치의 현재 진행률을 가져오려면 [XPackageGetInstallationProgress](/reference/system/xpackage/functions/xpackagegetinstallationprogress)를 호출합니다. 설치 중 변경 알림을 받으려면 콜백을 등록합니다.

전체 패키지 또는 특정 하위 집합에 대한 설치 모니터를 만들 수 있습니다. 여기서는 트랙 이름에 대한 설치 진행률을 알고 싶다고 하는 “선택자”를 정의했습니다. 설치 모니터가 진행률 스냅샷을 얼마나 자주 업데이트할지 나타내는 빈도(이 경우 1000ms)를 지정하여 이 속도까지 업데이트되도록 할 수 있습니다. 시간 내에 진행이 이루어지지 않은 경우에는 더 느릴 수 있습니다.

```cpp theme={null}
XPackageRegisterInstallationProgressChanged(
    monitor,
    nullptr,
    ProgressChangedCallback,
    &token);
```

트랙 로딩이 언제 완료되는지 알고 싶으므로 모니터에 진행률 변경 이벤트를 등록합니다. 이 콜백은 모니터가 생성될 때 제공된 작업 큐를 통해 호출되며, 대략 [XPackageCreateInstallationMonitor](/reference/system/xpackage/functions/xpackagecreateinstallationmonitor)에서 지정한 주기로 호출됩니다. 콜백 내에서 게임 내 진행률을 렌더링하거나 게임에 트랙이 준비되었음을 알릴 수 있습니다.

이 예제에서는 설치 모니터를 닫지만 알림을 등록 취소하지 않습니다. 설치 모니터 알림의 수명은 설치 모니터에 연결되어 있으므로, 모니터를 닫으면 모니터에 대한 모든 알림이 등록 취소됩니다.

## 요구 사항

**헤더:** XPackage.h

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

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

## 개념 문서

* [Intelligent Delivery: 언어 지정자](/build/core-features/common/packaging/intelligentdelivery-language)
* [스트리밍 설치: 상태](/build/core-features/common/packaging/packaging-installstatus)

## 함께 보기

[XPackage](/reference/system/xpackage/xpackage_members)\
[스트리밍 설치 및 Intelligent Delivery](/build/core-features/common/packaging/overviews/streaming_install-intelligent_delivery)\
[XPackageGetInstallationProgress](/reference/system/xpackage/functions/xpackagegetinstallationprogress)\
[XPackageCreateInstallationMonitor](/reference/system/xpackage/functions/xpackagecreateinstallationmonitor)


## Related topics

- [XPackageInstallationProgressCallback](/ko/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [XPackageUnregisterInstallationProgressChanged](/ko/reference/system/xpackage/functions/xpackageunregisterinstallationprogresschanged.md)
- [스트리밍 설치: 상태](/ko/build/core-features/common/packaging/packaging-installstatus.md)
- [XTaskQueueRegistrationToken](/ko/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken.md)
- [XPackage](/ko/reference/system/xpackage/xpackage_members.md)