Skip to main content

XUserAddAsync

以非同步方式將使用者新增至遊戲工作階段。

語法

參數

options   _In_
類型:XUserAddOptions
將使用者新增至遊戲工作階段的選項。 async   _Inout_
類型:XAsyncBlock*
用於輪詢呼叫狀態並擷取呼叫結果的 XAsyncBlock。

傳回值

類型:HRESULT HRESULT 成功或錯誤碼。 如需錯誤碼清單,請參閱錯誤碼。

備註

XUserAddAsync 會啟動非同步作業,將使用者新增至遊戲。請使用 XUserAddResult 來擷取作業的結果。 除非將 XUserAddOptions::AddDefaultUserSilently 或 XUserAddOptions::AddDefaultUserAllowingUI 傳遞給 options 參數,否則 XUserAddAsync 一律會顯示帳戶選擇器 UI。 如果您使用 XUserAddOptions::AddDefaultUserSilently,XUserAddAsync 不會顯示 UI。 使用簡化使用者模型 (NDA 主題) 時,此函式有一些注意事項:
  • 使用簡化使用者模型時,開發人員應確定 options 設定為 XUserAddOptions::AddDefaultUserSilently:
  • 在主機上,除非已有預設使用者登入,否則使用簡化使用者模型的鬆散部署遊戲將不允許 啟動。
  • 在 PC 上,使用簡化使用者模型的鬆散部署遊戲可以在沒有使用者的情況下啟動; 不過,當遊戲呼叫 XUserAddAsync 時,如果沒有任何人登入,遊戲將會 終止,並啟動 PC Bootstrapper 來協助使用者登入。只要使用者已完全登入 XBOX Live, 後續啟動就會正常運作。
如果開發人員以設定為 XUserAddOptions::AddDefaultUserSilently 的 options 重複 呼叫 XUserAddAsync,應該了解一些邊緣案例:
  • 如果您重複呼叫此函式,且我們知道啟動遊戲的預設使用者,則會傳回同一位使用者。
  • 如果先前已知的預設使用者已登出,且裝置上只有一位已登入的使用者,則會 將該使用者標示為新的「預設」使用者並傳回該使用者。
  • 如果先前已知的預設使用者已登出,且裝置上有多位已登入的使用者,則 會傳回 E_GAMEUSER_NO_DEFAULT_USER。
如果沒有可用的預設使用者,XUserAddResult 會傳回 E_GAMEUSER_NO_DEFAULT_USER。您必須以未設定為 XUserAddOptions::AddDefaultUserSilently 的 options 呼叫 XUserAddAsync。 如果開發人員以設定為 XUserAddOptions::AddDefaultUserAllowingUI 的 options 重複呼叫 XUserAddAsync,也應該了解一些邊緣案例。這些案例與無訊息 UI 的情況 非常類似 (但不完全相同):
  • 如果您重複呼叫此函式,且我們知道啟動遊戲的預設使用者,則會傳回同一位使用者。
  • 如果先前已知的預設使用者已登出,且裝置上只有一位已登入的使用者,則會將該使用者標示為新的「預設」使用者並傳回該使用者。
  • 如果最初啟動遊戲的使用者已登出,且使用者數目為 0 或超過 1 位,系統會顯示 UI 以取得使用者,然後將該使用者設定為預設使用者。
您無法將 XUserAddOptions::AllowGuests 與 XUserAddOptions::AddDefaultUserSilently 一起使用。來賓不能是預設使用者。無論目前的平台是否支援來賓, 您都可以放心使用 XUserAddOptions::AllowGuests。 您從 XUsers API 擷取的每個 XUserHandle 控制代碼,都必須呼叫 XUserCloseHandle 關閉一次 (且僅限一次)。 XUserAddAsync 成功完成時會執行輸入裝置配對。如果由於 XUserAddOptions::AddDefaultUserSilently 或 XUserAddOptions::AddDefaultUserAllowingUI 選項而在沒有 UI 的情況下自動登入,則系統中指派給使用者的輸入裝置會傳播至遊戲。如果登入時顯示了 UI,則選取該使用者的輸入裝置會指派給該使用者。 可以透過 XUserRegisterForDeviceAssociationChanged 方法追蹤裝置關聯。 下列範例示範如何以非同步方式將使用者新增至遊戲工作階段。

需求

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

概念文件

另請參閱

XUser XUserAddOptions XUserCloseHandle
Last modified on October 6, 2026