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

# XPackageInstallationProgressCallback

> XPackageInstallationProgressCallback

# XPackageInstallationProgressCallback

[XPackageRegisterInstallationProgressChanged](/zh-TW/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged) 所使用的回呼。

## 語法

```cpp theme={null}
void XPackageInstallationProgressCallback(  
         void* context,  
         XPackageInstallationMonitorHandle monitor  
)  
```

### 參數

*context*   \_In\_\
類型：void\*

傳遞給 [XPackageRegisterInstallationProgressChanged](/zh-TW/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged) 的內容。

*monitor*   \_In\_\
類型：XPackageInstallationMonitorHandle

安裝作業的安裝監視器。

### 傳回值

類型：void

## 備註

**PackageInstallationProgressCallback** 會依照註冊 ProgressChanged 通知時所指定的頻率呼叫。

遊戲可以實作啟動標記，以便在完全安裝之前就能執行。遊戲需要知道哪些部分已安裝、哪些尚未安裝。在下列範例中，遊戲需要知道與指定賽道名稱之賽道相關聯的區塊何時安裝完成：

```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 主機

## 另請參閱

[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

- [XPackageInstallationProgressCallback](/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [XPackageRegisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged.md)
- [XPackage](/reference/system/xpackage/xpackage_members.md)
- [XPackageGetInstallationProgress](/reference/system/xpackage/functions/xpackagegetinstallationprogress.md)
- [XPackageUnregisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageunregisterinstallationprogresschanged.md)