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

# XUserGetGamertag

> XUserGetGamertag

# XUserGetGamertag

检索特定用户的玩家代号。

## 语法

```cpp theme={null}
HRESULT XUserGetGamertag(  
         XUserHandle user,
         XUserGamertagComponent gamertagComponent,
         size_t gamertagSize,  
         char* gamertag,  
         size_t* gamertagUsed  
)  
```

### 参数

*user*   \_In\_\
类型：XUserHandle

要检索玩家代号的用户的句柄。

*gamertagComponent*   \_In\_\
类型：[XUserGamertagComponent](/reference/system/xuser/enums/xusergamertagcomponent)

要检索的玩家代号类型。

*gamertagSize*   \_In\_\
类型：size\_t

*gamertag* 参数中缓冲区的大小（以字节为单位）。

*gamertag*   \_Out\_writes\_bytes\_to\_(gamertagSize,*gamertagUsed)\
类型：char*

包含特定用户的玩家代号。

*gamertagUsed*   \_Out\_opt\_\
类型：size\_t\*

包含用于存放玩家代号的缓冲区数量。

### 返回值

类型：HRESULT

HRESULT 成功或错误代码。

| 返回代码                                        | 说明                                                                                                                            |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| S\_OK                                       | 操作成功。                                                                                                                         |
| E\_GAMEUSER\_RESOLVE\_USER\_ISSUE\_REQUIRED | 用户必须使用 UI 来解决该问题。调用 [XUserResolveIssueWithUiAsync](/reference/system/xuser/functions/xuserresolveissuewithuiasync) 以向用户显示 UI。 |
| E\_INSUFFICIENT\_BUFFER                     | *gamertagSize* 所指示的缓冲区大小不足以容纳所请求的组件。                                                                                          |
| E\_INVALIDARG                               | 提供的 *gamertagComponent* 无效。                                                                                                   |

有关错误代码列表，请参阅[错误代码](/reference/errorcodes)。

## 注解

若要检索特定用户的用户 ID，请调用 [XUserGetId](/reference/system/xuser/functions/xusergetid)。

若要检索特定用户的状态，请调用 [XUserGetState](/reference/system/xuser/functions/xusergetstate)。

若要检索特定用户的年龄组，请调用 [XUserGetAgeGroup](/reference/system/xuser/functions/xusergetagegroup)。

## 要求

**头文件：** XUser.h

**库：** xgameruntime.lib

**支持的平台：** Windows、Steam Deck、XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[XUser](/reference/system/xuser/xuser_members)

[XUserGetId](/reference/system/xuser/functions/xusergetid)

[XUserGetState](/reference/system/xuser/functions/xusergetstate)

[XUserGetAgeGroup](/reference/system/xuser/functions/xusergetagegroup)


## Related topics

- [XUserGamertagComponent](/zh-CN/reference/system/xuser/enums/xusergamertagcomponent.md)
- [现代游戏玩家代号的最佳实践和测试](/zh-CN/services/xbox-services/fundamentals/identity/user-profile/gamertags/live-modern-gamertags-best-practices-and-testing.md)
- [XR-046 显示名称和游戏图片](/zh-CN/publishing/certification/xr/xr-046.md)
- [游戏玩家代号概述](/zh-CN/services/xbox-services/fundamentals/identity/user-profile/gamertags/live-gamertags-overview.md)
- [XBOX 认证概览](/zh-CN/publishing/certification/overview.md)