> ## 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\*](/zh-TW/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken)

識別回呼的權杖，之後可使用 [XPackageUnregisterInstallationProgressChanged](/zh-TW/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,         // 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 呼叫：

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

所有已安裝的內容都會有唯一識別碼。如果您知道套件的識別碼並且能夠存取該內容，就可以監視任何套件的安裝。執行中的處理程序可以取得自己的套件識別碼。如需套件識別碼的詳細資訊，請參閱[管理可下載內容 (DLC) 並授權](/zh-TW/publishing/xstore-commerce/xstore-dlc)。

```cpp theme={null}
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](/zh-TW/reference/system/xpackage/functions/xpackagegetinstallationprogress)；若要在安裝期間收到變更通知，請註冊回呼。

您可以針對整個套件或特定子集建立安裝監視器。在這裡，您定義了一個「選取器」，表示您想知道某個賽道名稱的安裝進度。您可以指定頻率 (在此例中為 1000 毫秒)，表示安裝監視器更新其進度快照的頻率，最快可達此速度。如果在這段時間內沒有任何進度，則可能會較慢。

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

您想知道賽道何時載入完成，因此您在監視器上註冊進度變更事件。此回呼會透過建立監視器時所提供的工作佇列叫用，頻率大致與 [XPackageCreateInstallationMonitor](/zh-TW/reference/system/xpackage/functions/xpackagecreateinstallationmonitor) 中指定的相同。在回呼內，您可以呈現遊戲內進度，或通知遊戲賽道已就緒。

在此範例中，您關閉了安裝監視器，但沒有取消註冊通知。安裝監視器通知的存留期與安裝監視器綁定；因此，關閉監視器會取消註冊其所有通知。

## 需求

**標頭：** XPackage.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [Intelligent Delivery：語言指定元](/zh-TW/build/core-features/common/packaging/intelligentdelivery-language)
* [串流安裝：狀態](/zh-TW/build/core-features/common/packaging/packaging-installstatus)

## 另請參閱

[XPackage](/zh-TW/reference/system/xpackage/xpackage_members)\
[串流安裝和 Intelligent Delivery](/zh-TW/build/core-features/common/packaging/overviews/streaming_install-intelligent_delivery)\
[XPackageGetInstallationProgress](/zh-TW/reference/system/xpackage/functions/xpackagegetinstallationprogress)\
[XPackageCreateInstallationMonitor](/zh-TW/reference/system/xpackage/functions/xpackagecreateinstallationmonitor)


## Related topics

- [XPackageRegisterInstallationProgressChanged](/ja-jp/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged.md)
- [XPackageUnregisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageunregisterinstallationprogresschanged.md)
- [XPackageInstallationProgressCallback](/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [Streaming installation: status](/build/core-features/common/packaging/packaging-installstatus.md)
- [流式安装:状态](/zh-CN/build/core-features/common/packaging/packaging-installstatus.md)