Skip to main content

XUserAddAsync

ゲーム セッションにユーザーを非同期に追加します。

構文

パラメーター

options   _In_
Type: XUserAddOptions
ゲーム セッションにユーザーを追加するためのオプションです。 async   _Inout_
Type: XAsyncBlock*
呼び出しの状態のポーリングおよび呼び出し結果の取得に使用する XAsyncBlock

戻り値

Type: HRESULT HRESULT の成功またはエラー コード。 エラー コードの一覧については、エラー コード を参照してください。

解説

XUserAddAsync は、ユーザーをゲームに追加するための非同期操作を開始します。操作の結果を取得するには、XUserAddResult を使用します。 XUserAddAsync は、options パラメーターに XUserAddOptions::AddDefaultUserSilently または XUserAddOptions::AddDefaultUserAllowingUI のいずれかが渡されない限り、常にアカウント ピッカー UI を表示します。 XUserAddOptions::AddDefaultUserSilently を使用する場合、XUserAddAsync は UI を表示しません。 簡易ユーザー モデル (NDA トピック) を使用する際、この関数にはいくつかの考慮事項があります:
  • 簡易ユーザー モデルでは、開発者は optionsXUserAddOptions::AddDefaultUserSilently に設定されるようにしてください:
  • 本体では、簡易ユーザー モデルを使用してルーズにデプロイされたゲームは、既定のユーザーが既にサインインしていなければ起動できません。
  • PC では、簡易ユーザー モデルを使用してルーズにデプロイされたゲームは、ユーザーなしで起動できます。ただし、ゲームが XUserAddAsync を呼び出したときに誰もサインインしていない場合、ゲームは終了され、PC ブートストラッパーが起動してユーザーのサインインを支援します。以降の起動は、ユーザーが XBOX Live に完全にサインインしている限り正常に動作します。
optionsXUserAddOptions::AddDefaultUserSilently を設定して XUserAddAsync を繰り返し呼び出す場合、開発者が知っておくべきエッジ ケースがいくつかあります:
  • ゲームを起動した既定のユーザーが判明している状態でこれを繰り返し呼び出すと、同じユーザーが返されます。
  • 以前に判明していた既定のユーザーがサインアウトしており、デバイスに 1 人のユーザーだけがサインインしている場合、そのユーザーが新しい「既定」のユーザーとしてマークされ、そのユーザーが返されます。
  • 以前に判明していた既定のユーザーがサインアウトしており、デバイスに複数のユーザーがサインインしている場合、E_GAMEUSER_NO_DEFAULT_USER が返されます。
既定のユーザーが利用できない場合、XUserAddResult は E_GAMEUSER_NO_DEFAULT_USER を返します。optionsXUserAddOptions::AddDefaultUserSilently を設定せずに XUserAddAsync を呼び出す必要があります。 optionsXUserAddOptions::AddDefaultUserAllowingUI を設定して XUserAddAsync を繰り返し呼び出す場合にも、開発者が知っておくべきエッジ ケースがいくつかあります。これらは、サイレント UI の場合と非常に似ています (ただし同一ではありません):
  • ゲームを起動した既定のユーザーが判明している状態でこれを繰り返し呼び出すと、同じユーザーが返されます。
  • 以前に判明していた既定のユーザーがサインアウトしており、デバイスに 1 人のユーザーだけがサインインしている場合、そのユーザーが新しい「既定」のユーザーとしてマークされ、そのユーザーが返されます。
  • 最初にゲームを起動したユーザーがサインアウトしており、ユーザー数が 0 人または 2 人以上の場合、システムはユーザーを取得するために UI を表示し、そのユーザーを既定として設定します。
XUserAddOptions::AllowGuestsXUserAddOptions::AddDefaultUserSilently と一緒に使用することはできません。ゲストは既定のユーザーになれません。現在のプラットフォームがゲストをサポートしているかどうかに関係なく、XUserAddOptions::AllowGuests を安全に使用できます。 XUsers API から取得したそれぞれの XUserHandle ハンドルは、XUserCloseHandle を呼び出して 1 回だけ閉じる必要があります。 入力デバイスのペアリングは、XUserAddAsync の正常完了時に実行されます。XUserAddOptions::AddDefaultUserSilently または XUserAddOptions::AddDefaultUserAllowingUI オプションによって UI なしで自動的にサインインが行われた場合、システム内でユーザーに割り当てられている入力デバイスがタイトルに伝達されます。サインインのために UI が表示された場合、ユーザーを選択した入力デバイスがそのユーザーに割り当てられます。 デバイスの関連付けは、XUserRegisterForDeviceAssociationChanged メソッドを介して追跡できます。 次の例では、ゲーム セッションにユーザーを非同期に追加する方法を示します。

要件

ヘッダー: XUser.h ライブラリ: xgameruntime.lib サポートされているプラットフォーム: Windows、Steam Deck、XBOX One 本体、XBOX Series 本体

概念ドキュメント

関連項目

XUser XUserAddOptions XUserCloseHandle
最終更新日 2026年8月24日