Skip to main content

XPackageCreateInstallationMonitor

建立安裝狀態的監視器。

語法

參數

packageIdentifier   _In_z_
類型:char*
唯一識別磁碟上已安裝套件的字串。如需套件識別碼的詳細資訊,請參閱管理可下載內容 (DLC) 及授權。 selectorCount   _In_
類型:uint32_t
selectors 參數中的選取器數目。 selectors   _In_reads_opt_(selectorCount)
類型:XPackageChunkSelector*
指定要監視之區塊的選取器陣列。 minimumUpdateIntervalMs   _In_
類型:uint32_t
監視器的解析度,以毫秒為單位。 queue   _In_opt_
類型:XTaskQueueHandle
執行更新的佇列。 installationMonitor   _Out_
類型:XPackageInstallationMonitorHandle*
傳回時,指向已建立的安裝監視器。

傳回值

類型:HRESULT HRESULT 成功或錯誤碼。

備註

在時間敏感的執行緒上呼叫此函式並不安全。如需詳細資訊,請參閱時間敏感的執行緒。
XPackageCreateInstallationMonitor 會建立追蹤安裝狀態的監視器。監視器會依照指定更新間隔所決定的固定頻率自行更新及重新整理。更新會排程在指定的工作佇列上。間隔為零表示永不執行更新,並會建立一個僅為安裝之一次性快照的安裝監視器。如果傳遞零間隔,queue 參數可以是 null。 若要取得安裝的目前進度,請呼叫 XPackageGetInstallationProgress;若要在安裝期間收到變更通知,請註冊回呼。此安裝監視器可以為整個套件或特定子集建立。 某個遊戲已實作啟動標記,因此可以在完全安裝之前執行。遊戲需要知道哪些部分已安裝、哪些部分尚未安裝。在此範例中,遊戲需要知道與指定賽道名稱之賽道相關聯的區塊何時已安裝:
讓我們逐一說明上述程式碼中的每個 API 呼叫:
所有已安裝的內容都會有唯一識別碼。如果您知道任何套件的識別碼,而且有權存取該內容,就可以監視該套件的安裝。執行中的處理程序可以取得自己的套件識別碼。
這會建立追蹤安裝狀態的監視器。此安裝監視器會定期自行更新。若要取得安裝的目前進度,請呼叫 XPackageGetInstallationProgress;若要在安裝期間收到變更通知,請註冊回呼。 您可以為整個套件或特定子集建立安裝監視器。在這裡,您定義了一個「選取器」,表示您想要知道某個賽道名稱的安裝進度。您可以指定頻率 (在此例中為 1000 毫秒),表示安裝監視器更新其進度快照的頻率,最快可達此速度。如果在這段時間內沒有任何進度,更新可能會較慢。
您想知道賽道何時完成載入,因此在監視器上註冊進度變更事件。此回呼會透過建立監視器時提供的工作佇列叫用,大約依照 XPackageCreateInstallationMonitor 中指定的頻率。在回呼內,您可以轉譯遊戲內的進度,或通知遊戲賽道已就緒。 在此範例中,您關閉了安裝監視器,但沒有取消註冊通知。安裝監視器通知的存留期與安裝監視器繫結;因此,關閉監視器會取消註冊它的所有通知。

需求

標頭: XPackage.h 程式庫: xgameruntime.lib 支援的平台: Windows、XBOX One 系列主機與 XBOX Series 主機

概念文件

另請參閱

XPackage
Last modified on October 6, 2026