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

# XPackageGetInstallationProgress

> XPackageGetInstallationProgress

# XPackageGetInstallationProgress

傳回安裝的目前進度。

## 語法

```cpp theme={null}
void XPackageGetInstallationProgress(  
         XPackageInstallationMonitorHandle installationMonitor,  
         XPackageInstallationProgress* progress  
)  
```

### 參數

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

安裝監視器的控制代碼。

*progress*   \_Out\_\
類型：[XPackageInstallationProgress\*](/zh-TW/reference/system/xpackage/structs/xpackageinstallationprogress)

傳回時，包含安裝的目前進度。

### 傳回值

類型：void

## 備註

若要取得安裝的目前進度，請呼叫 [XPackageGetInstallationProgress](/zh-TW/reference/system/xpackage/functions/xpackagegetinstallationprogress)；若要在安裝期間收到變更通知，請註冊回呼。您可以為整個套件或特定子集建立安裝監視器。

在全新安裝新內容期間，有一小段時間執行階段無法計算套件的總大小，因為安裝尚未完全開始。在此情況下，執行階段會傳回 UINT64\_MAX 作為 totalBytes 的值，並針對所有其他欄位傳回零或 false。

範例：

```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}
hr = 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)

## 另請參閱

[XPackage](/zh-TW/reference/system/xpackage/xpackage_members)


## Related topics

- [XPackageGetInstallationProgress](/reference/system/xpackage/functions/xpackagegetinstallationprogress.md)
- [XPackageInstallationProgressCallback](/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [XPackageRegisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged.md)
- [XPackageUpdateInstallationMonitor](/reference/system/xpackage/functions/xpackageupdateinstallationmonitor.md)