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

# XPackageCreateInstallationMonitor

> XPackageCreateInstallationMonitor

# XPackageCreateInstallationMonitor

建立安裝狀態的監視器。

## 語法

```cpp theme={null}
HRESULT XPackageCreateInstallationMonitor(  
         const char* packageIdentifier,  
         uint32_t selectorCount,  
         XPackageChunkSelector* selectors,  
         uint32_t minimumUpdateIntervalMs,  
         XTaskQueueHandle queue,  
         XPackageInstallationMonitorHandle* installationMonitor  
)  
```

### 參數

*packageIdentifier*   \_In\_z\_\
類型：char\*

唯一識別磁碟上已安裝套件的字串。如需套件識別碼的詳細資訊，請參閱[管理可下載內容 (DLC) 及授權](/zh-TW/publishing/xstore-commerce/xstore-dlc)。

*selectorCount*   \_In\_\
類型：uint32\_t

*selectors* 參數中的選取器數目。

*selectors*   \_In\_reads\_opt\_(selectorCount)\
類型：[XPackageChunkSelector\*](/zh-TW/reference/system/xpackage/structs/xpackagechunkselector)

指定要監視之區塊的選取器陣列。

*minimumUpdateIntervalMs*   \_In\_\
類型：uint32\_t

監視器的解析度，以毫秒為單位。

*queue*   \_In\_opt\_\
類型：XTaskQueueHandle

執行更新的佇列。

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

傳回時，指向已建立的安裝監視器。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。

## 備註

<Note>在時間敏感的執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感的執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

**XPackageCreateInstallationMonitor** 會建立追蹤安裝狀態的監視器。監視器會依照指定更新間隔所決定的固定頻率自行更新及重新整理。更新會排程在指定的工作佇列上。間隔為零表示永不執行更新，並會建立一個僅為安裝之一次性快照的安裝監視器。如果傳遞零間隔，queue 參數可以是 null。

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

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

```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); 
```

所有已安裝的內容都會有唯一識別碼。如果您知道任何套件的識別碼，而且有權存取該內容，就可以監視該套件的安裝。執行中的處理程序可以取得自己的套件識別碼。

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

## 概念文件

* [串流安裝：狀態](/zh-TW/build/core-features/common/packaging/packaging-installstatus)
* [時間敏感的執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)
* [檢查更新](/zh-TW/publishing/xstore-commerce/xstore-checking-updates)

## 另請參閱

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


## Related topics

- [XPackageCreateInstallationMonitor](/reference/system/xpackage/functions/xpackagecreateinstallationmonitor.md)
- [XPackageInstallationProgressCallback](/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [XPackageRegisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged.md)
- [Streaming installation: status](/build/core-features/common/packaging/packaging-installstatus.md)
- [XPackageCloseInstallationMonitorHandle](/reference/system/xpackage/functions/xpackagecloseinstallationmonitorhandle.md)