> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XUser（API 内容）

> XUser

# XUser

XUser API 的参考资料。

## 函数

| 函数 | 描述 |
| - | - |
| [XUserAddAsync](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuseraddasync.md) | 异步地将用户添加到游戏会话。 |
| [XUserAddByIdWithUiAsync](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuseraddbyidwithuiasync.md) | 根据来自游戏邀请的 XUID 将用户异步添加到游戏会话。此函数仅应用于响应游戏邀请。 |
| [XUserAddByIdWithUiResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuseraddbyidwithuiresult.md) | 检索 XUserAddByIdWithUiAsync 创建的用户句柄。此函数仅应用于响应游戏邀请。 |
| [XUserAddResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuseraddresult.md) | 检索 XUserAddAsync 创建的用户句柄。 |
| [XUserChangeEventCallback](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserchangeeventcallback.md) | 应用程序为用户更改事件定义的回调。 |
| [XUserCheckPrivilege](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusercheckprivilege.md) | 确定用户是否具有特定权限。 |
| [XUserCloseHandle](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserclosehandle.md) | 关闭特定用户句柄。 |
| [XUserCloseSignOutDeferralHandle](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserclosesignoutdeferralhandle.md) | 关闭特定用户注销延迟句柄。 |
| [XUserCompare](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusercompare.md) | 比较两个用户句柄是否相等。 |
| [XUserDefaultAudioEndpointUtf16ChangedCallback](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserdefaultaudioendpointutf16changedcallback.md) | 应用程序定义并在用户的默认音频终结点更改时调用的回调。 |
| [XUserDeviceAssociationChangedCallback](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserdeviceassociationchangedcallback.md) | 当用户-设备关联更改时调用的回调。 |
| [XUserDuplicateHandle](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserduplicatehandle.md) | 复制用户句柄。 |
| [XUserFindControllerForUserWithUiAsync](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserfindcontrollerforuserwithuiasync.md) | 显示一个对话框，提示用户开启并识别他们想要使用的控制器。 |
| [XUserFindControllerForUserWithUiResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserfindcontrollerforuserwithuiresult.md) | 检索用户选择使用的应用程序本地设备 ID (APP\_LOCAL\_DEVICE\_ID)。 |
| [XUserFindForDevice](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserfindfordevice.md) | 检索特定设备 ID 对应的用户 ID。 |
| [XUserFindUserById](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserfinduserbyid.md) | 检索本地用户的 XBOX 用户 ID (XUID)。 |
| [XUserFindUserByLocalId](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserfinduserbylocalid.md) | 检索特定本地用户 ID 的用户句柄。 |
| [XUserGetAgeGroup](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetagegroup.md) | 返回用户的年龄组。 |
| [XUserGetDefaultAudioEndpointUtf16](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetdefaultaudioendpointutf16.md) | 检索特定用户的默认音频终结点。 |
| [XUserGetGamerPictureAsync](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetgamerpictureasync.md) | 异步检索特定用户的玩家图片。 |
| [XUserGetGamerPictureResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetgamerpictureresult.md) | 检索对 XUserGetGamerPictureAsync 的调用结果。 |
| [XUserGetGamerPictureResultSize](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetgamerpictureresultsize.md) | 返回 [XUserGetGamerPictureResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetgamerpictureresult.md) 检索 ]XUserGetGamerPictureAsync]\(/zh-CN/reference/system/xuser/functions/xusergetgamerpictureasync) 返回的玩家图片所需的缓冲区大小。 |
| [XUserGetGamertag](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetgamertag.md) | 检索特定用户的玩家代号。 |
| [XUserGetId](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetid.md) | 获取特定用户的用户 ID。 |
| [XUserGetIsGuest](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetisguest.md) | 返回一个布尔值，指示用户是否为访客。 |
| [XUserGetLocalId](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetlocalid.md) | 检索用户的唯一游戏会话 ID。 |
| [XUserGetMaxUsers](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetmaxusers.md) | 检索当前平台上游戏会话允许的最大用户数。 |
| [XUserGetMsaTokenSilentlyAsync](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetmsatokensilentlyasync.md) | 此函数现已弃用。 |
| [XUserGetMsaTokenSilentlyResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetmsatokensilentlyresult.md) | 此函数现已弃用。 |
| [XUserGetMsaTokenSilentlyResultSize](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetmsatokensilentlyresultsize.md) | 此函数现已弃用。 |
| [XUserGetSignOutDeferral](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetsignoutdeferral.md) | 检索注销延迟的句柄。 |
| [XUserGetState](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergetstate.md) | 检索用户的状态。 |
| [XUserGetTokenAndSignatureAsync](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergettokenandsignatureasync.md) | 异步检索 Web 请求的 xtoken 和签名。 |
| [XUserGetTokenAndSignatureResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergettokenandsignatureresult.md) | 获取对 XUserGetTokenAndSignatureAsync 的调用结果。 |
| [XUserGetTokenAndSignatureResultSize](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergettokenandsignatureresultsize.md) | 获取保存 XUserGetTokenAndSignatureAsync 调用结果所需的缓冲区大小。 |
| [XUserGetTokenAndSignatureUtf16Async](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergettokenandsignatureutf16async.md) | 异步检索 Web 请求的 Unicode xtoken 和签名。 |
| [XUserGetTokenAndSignatureUtf16Result](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergettokenandsignatureutf16result.md) | 获取对 XUserGetTokenAndSignatureUtf16Async 的调用结果。 |
| [XUserGetTokenAndSignatureUtf16ResultSize](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xusergettokenandsignatureutf16resultsize.md) | 获取保存 XUserGetTokenAndSignatureUtf16Async 调用结果所需的缓冲区大小。 |
| [XUserIsStoreUser](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserisstoreuser.md) | 检查 XUser MSA 是否与登录到 Microsoft Store 的 MSA 相同。 |
| [XUserRegisterForChangeEvent](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserregisterforchangeevent.md) | 注册用户更改事件的回调。 |
| [XUserRegisterForDefaultAudioEndpointUtf16Changed](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserregisterfordefaultaudioendpointutf16changed.md) | 注册应用程序定义并在默认音频终结点更改时调用的回调。 |
| [XUserRegisterForDeviceAssociationChanged](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserregisterfordeviceassociationchanged.md) | 为用户设备关联更改事件注册回调。 |
| [XUserResolveIssueWithUiAsync](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserresolveissuewithuiasync.md) | 显示用于解决非 Unicode URL 令牌问题的系统用户界面。 |
| [XUserResolveIssueWithUiResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserresolveissuewithuiresult.md) | 检索对 XUserResolveIssueWithUiAsync 的调用结果。 |
| [XUserResolveIssueWithUiUtf16Async](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserresolveissuewithuiutf16async.md) | 显示用于解决特定 Unicode URL 令牌问题的系统用户界面。 |
| [XUserResolveIssueWithUiUtf16Result](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserresolveissuewithuiutf16result.md) | 检索对 XUserResolveIssueWithUiUtf16Async 的调用结果。 |
| [XUserResolvePrivilegeWithUiAsync](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserresolveprivilegewithuiasync.md) | 显示所需用户权限的解决方案用户界面。 |
| [XUserResolvePrivilegeWithUiResult](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserresolveprivilegewithuiresult.md) | 检索对 XUserResolvePrivilegeWithUiAsync 的调用结果。 |
| [XUserUnregisterForChangeEvent](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserunregisterforchangeevent.md) | 注销之前注册的用户更改回调。 |
| [XUserUnregisterForDefaultAudioEndpointUtf16Changed](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserunregisterfordefaultaudioendpointutf16changed.md) | 注销之前注册的默认音频终结点更改回调。 |
| [XUserUnregisterForDeviceAssociationChanged](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserunregisterfordeviceassociationchanged.md) | 注销之前注册的用户设备关联更改回调。 |
| [xUserPlatformRemoteConnectSetEventHandlers](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserplatformremoteconnectseteventhandlers.md) | 设置远程连接事件处理程序 |
| [XUserPlatformRemoteConnectCancelPrompt](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserplatformremoteconnectcancelprompt.md) | 向 XUser 发出信号，表明用户已关闭远程连接提示。 |
| [XUserPlatformRemoteConnectShowPromptEventHandler](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserplatformremoteconnectshowprompteventhandler.md) | 用于远程连接身份验证的显示提示事件处理程序。 |
| [XUserPlatformRemoteConnectClosePromptEventHandler](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserplatformremoteconnectcloseprompteventhandler.md) | 用于远程身份验证的关闭提示事件处理程序。 |
| [XUserPlatformSpopPromptEventHandler](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserplatformspopprompteventhandler.md) | SPOP 操作事件处理程序的显示提示 |
| [XUserPlatformSpopPromptSetEventHandlers](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserplatformspoppromptseteventhandlers.md) | 设置 SPOP 提示事件处理程序。 |
| [XUserPlatformSpopPromptClearEventHandler](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserplatformspoppromptcleareventhandler) | 清除 XUser 中的 SPOP 提示事件处理程序。 |
| [XUserPlatformSpopPromptComplete](https://docs.xbox.com/zh-CN/reference/system/xuser/functions/xuserplatformspoppromptcomplete.md) | 向 XUser 发出信号，表明用户已完成与 SPOP 提示的交互。 |

## 结构

| 结构 | 描述 |
| - | - |
| [APP\_LOCAL\_DEVICE\_ID](https://docs.xbox.com/zh-CN/reference/system/xuser/structs/app_local_device_id.md) | 指定本地输入设备的根 ID。 |
| [XUserDeviceAssociationChange](https://docs.xbox.com/zh-CN/reference/system/xuser/structs/xuserdeviceassociationchange.md) | 指定当设备关联发生更改时旧的和新的设备关联。 |
| [XUserGetTokenAndSignatureData](https://docs.xbox.com/zh-CN/reference/system/xuser/structs/xusergettokenandsignaturedata.md) | 指定为 Web 请求所检索的 xtoken 和签名。 |
| [XUserGetTokenAndSignatureHttpHeader](https://docs.xbox.com/zh-CN/reference/system/xuser/structs/xusergettokenandsignaturehttpheader.md) | 指定 Web 请求的 HTTP 标头。 |
| [XUserGetTokenAndSignatureUtf16Data](https://docs.xbox.com/zh-CN/reference/system/xuser/structs/xusergettokenandsignatureutf16data.md) | 包含 Web 请求的 Unicode xtoken 和签名。 |
| [XUserGetTokenAndSignatureUtf16HttpHeader](https://docs.xbox.com/zh-CN/reference/system/xuser/structs/xusergettokenandsignatureutf16httpheader.md) | 包含 Web 请求的 Unicode HTTP 标头。 |
| [XUserLocalId](https://docs.xbox.com/zh-CN/reference/system/xuser/structs/xuserlocalid.md) | 指定用户的游戏会话 ID。 |
| [XUserPlatformRemoteConnectEventHandlers](https://docs.xbox.com/zh-CN/reference/system/xuser/structs/xuserplatformremoteconnecteventhandlers.md) | 封装远程连接事件处理程序 |

## 枚举

| 枚举 | 描述 |
| - | - |
| [XUserAddOptions](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuseraddoptions.md) | 指定用于添加用户的选项。 |
| [XUserAgeGroup](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuseragegroup.md) | 指定用户的年龄组。 |
| [XUserChangeEvent](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuserchangeevent.md) | 指定用户更改事件的类型。 |
| [XUserDefaultAudioEndpointKind](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuserdefaultaudioendpointkind.md) | 指定用户的默认音频终结点用于呈现还是捕获音频。 |
| [XUserGamerPictureSize](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xusergamerpicturesize.md) | 指定玩家图片的大小（以像素为单位）。 |
| [XUserGamertagComponent](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xusergamertagcomponent.md) | 指定要获取的玩家代号的类型（或组件）。 |
| [XUserGetMsaTokenSilentlyOptions](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xusergetmsatokensilentlyoptions.md) | XUserGetMsaTokenSilentlyOptions 的选项。 |
| [XUserGetTokenAndSignatureOptions](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xusergettokenandsignatureoptions.md) | GetUserTokenAndSignatureAsync 的选项。 |
| [XUserPrivilege](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuserprivilege.md) | 指定用户的权限。 |
| [XUserPrivilegeDenyReason](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuserprivilegedenyreason.md) | 指定用户无法获得权限的原因。 |
| [XUserPrivilegeOptions](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuserprivilegeoptions.md) | 指定用户权限选项。 |
| [XUserState](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuserstate.md) | 指定用户的当前状态。 |
| [XUserPlatformOperationResult](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/XUserPlatformOperationResult.md) | 定义客户端操作结果的枚举 |
| [XUserPlatformSpopOperationResult](https://docs.xbox.com/zh-CN/reference/system/xuser/enums/xuserplatformspopoperationresult.md) | 定义客户端操作结果的枚举。 |

## 概念文档

* [异步编程设计目标和改进](https://docs.xbox.com/zh-CN/build/core-features/common/async/async-whitepaper.md)
* [WinHTTP 概览](https://docs.xbox.com/zh-CN/build/console-features/networking/web-requests/intro-winhttp.md)
* [Web 请求（内容）](https://docs.xbox.com/zh-CN/build/console-features/networking/web-requests/web-requests-toc.md)
* [时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)
* [在 Unity 项目中使用 GDK API 的 C# 包装器](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/tutorials/get-started-with-unity-pc/features/gdk-unity-api-wrappers)

## 另请参阅

[系统 API 参考](https://docs.xbox.com/zh-CN/reference/system/gc-reference-system-toc.md)

## 错误代码

XUser API 可能返回以下错误代码。有关完整列表，请参阅[错误代码](https://docs.xbox.com/zh-CN/reference/errorcodes.md)。

| 代码 | 值 | 描述 |
| - | - | - |
| E\_GAMEUSER\_MAX\_USERS\_ADDED | 0x89245100 | 无法添加此用户，因为已达到最大用户数量。 |
| E\_GAMEUSER\_SIGNED\_OUT | 0x89245101 | 由于用户已注销，无法执行该操作。 |
| E\_GAMEUSER\_RESOLVE\_USER\_ISSUE\_REQUIRED | 0x89245102 | 需要 UI 来解决此用户的问题。 |
| E\_GAMEUSER\_DEFERRAL\_NOT\_AVAILABLE | 0x89245103 | 现在请求延迟不合适。 |
| E\_GAMEUSER\_USER\_NOT\_FOUND | 0x89245104 | 未找到与该 ID 匹配的用户。 |
| E\_GAMEUSER\_NO\_TOKEN\_REQUIRED | 0x89245105 | 此调用不需要令牌。 |
| E\_GAMEUSER\_NO\_DEFAULT\_USER | 0x89245106 | 没有当前默认用户。如果收到此错误，请在不带 AddDefaultUserSilently 的情况下再次调用 XUserAddAsync。 |
| E\_GAMEUSER\_FAILED\_TO\_RESOLVE | 0x89245107 | 未能解决给定的权限。 |
| E\_GAMEUSER\_NO\_TITLE\_ID | 0x89245108 | 必须配置 XBOX Live TitleId。 |
| E\_GAMEUSER\_UNKNOWN\_GAME\_IDENTITY | 0x89245109 | 无法识别游戏身份。MSAAppId 和 TitleId 与与该游戏关联的不匹配。 |
| E\_GAMEUSER\_NO\_PACKAGE\_IDENTITY | 0x89245110 | 必须配置程序包身份。 |
| E\_GAMEUSER\_FAILED\_TO\_GET\_TOKEN | 0x89245111 | 令牌请求失败。 |
| E\_GAMEUSER\_INVALID\_APP\_CONFIGURATION | 0x89245112 | 游戏配置中的 MSAAppId 无效或未针对身份验证堆栈进行配置。 |
| E\_GAMEUSER\_MALFORMED\_MSAAPPID | 0x89245113 | 游戏配置中的 MSAAppId 与预期格式不匹配（16 字符字符串或 GUID）。 |
| E\_GAMEUSER\_INCONSISTENT\_MSAAPPID\_AND\_TITLEID | 0x89245114 | 游戏配置中的 MSAAppId 和 TitleId 与与该游戏关联的不匹配。 |


## Related topics

- [用户登录](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/identity/auth/live-authentication-nav.md)
- [身份验证](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/identity/auth/index.md)
- [账户身份验证和访问概述](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/identity/auth/live-authentication-overview.md)
- [XtfUser（API 内容）](https://docs.xbox.com/zh-CN/reference/tools/xtf/xtfuser/xtfuser-xbox-windows-n.md)
- [在 PC 上处理商店账号不匹配的场景](https://docs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-mismatched-accounts.md)