Skip to main content

XUserAddAsync

게임 세션에 사용자를 비동기적으로 추가합니다.

구문

매개변수

options   _In_
형식: XUserAddOptions
게임 세션에 사용자를 추가하기 위한 옵션입니다. async   _Inout_
형식: XAsyncBlock*
호출의 상태를 폴링하고 호출 결과를 가져오기 위한 XAsyncBlock입니다.

반환값

형식: HRESULT HRESULT 성공 또는 오류 코드입니다. 오류 코드 목록은 Error Codes를 참조하십시오.

설명

XUserAddAsync는 게임에 사용자를 추가하는 비동기 작업을 시작합니다. 작업 결과를 가져오려면 XUserAddResult를 사용합니다. XUserAddAsyncXUserAddOptions::AddDefaultUserSilently 또는 XUserAddOptions::AddDefaultUserAllowingUIoptions 매개변수에 전달되지 않는 한 항상 계정 선택 UI를 표시합니다. XUserAddOptions::AddDefaultUserSilently를 사용하는 경우 XUserAddAsync는 UI를 표시하지 않습니다. 간소화된 사용자 모델(NDA 항목)을 사용할 때 이 함수에는 몇 가지 고려 사항이 있습니다.
  • 간소화된 사용자 모델을 사용할 때, 개발자는 optionsXUserAddOptions::AddDefaultUserSilently로 설정되도록 해야 합니다.
  • 콘솔에서 간소화된 사용자 모델을 사용하는 loose-deployed 게임은 기본 사용자가 이미 로그인되어 있지 않으면 실행이 허용되지 않습니다.
  • PC에서 간소화된 사용자 모델을 사용하는 loose-deployed 게임은 사용자 없이도 실행할 수 있지만, 게임이 XUserAddAsync를 호출하고 로그인된 사용자가 없는 경우, 게임이 종료되며 사용자 로그인을 돕기 위해 PC Bootstrapper가 실행됩니다. 사용자가 XBOX Live에 완전히 로그인되어 있으면 이후 실행은 정상적으로 작동합니다.
optionsXUserAddOptions::AddDefaultUserSilently로 설정하여 XUserAddAsync를 반복해서 호출하는 경우 개발자가 알아야 할 몇 가지 예외적인 상황이 있습니다.
  • 이 함수를 반복해서 호출할 때 게임을 시작한 기본 사용자를 알고 있는 경우, 동일한 사용자를 반환합니다.
  • 이전에 알려진 기본 사용자가 로그아웃했고, 장치에 로그인된 사용자가 한 명뿐인 경우, 해당 사용자를 새 “기본” 사용자로 표시하고 반환합니다.
  • 이전에 알려진 기본 사용자가 로그아웃했고, 장치에 로그인된 사용자가 여러 명인 경우, E_GAMEUSER_NO_DEFAULT_USER를 반환합니다.
기본 사용자를 사용할 수 없는 경우, XUserAddResult는 E_GAMEUSER_NO_DEFAULT_USER를 반환합니다. optionsXUserAddOptions::AddDefaultUserSilently로 설정하지 않고 XUserAddAsync를 호출해야 합니다. optionsXUserAddOptions::AddDefaultUserAllowingUI로 설정하여 XUserAddAsync를 반복해서 호출하는 경우에도 개발자가 알아야 할 몇 가지 예외적인 상황이 있습니다. 이는 자동(무음) UI 경우와 매우 유사(동일하지는 않음)합니다.
  • 이 함수를 반복해서 호출할 때 게임을 시작한 기본 사용자를 알고 있는 경우, 동일한 사용자를 반환합니다.
  • 이전에 알려진 기본 사용자가 로그아웃했고, 장치에 로그인된 사용자가 한 명뿐인 경우, 해당 사용자를 새 “기본” 사용자로 표시하고 반환합니다.
  • 처음 게임을 시작한 사용자가 로그아웃했고, 사용자 수가 0명이거나 두 명 이상인 경우, 시스템이 UI를 표시하여 사용자를 가져오고 해당 사용자를 기본 사용자로 설정합니다.
XUserAddOptions::AllowGuestsXUserAddOptions::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
마지막 수정일 2026년 8월 24일