> ## 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.

# XInputGetKeystroke

> XInputGetKeystroke

# XInputGetKeystroke

检索游戏手柄输入事件。

## 语法

```cpp theme={null}
DWORD XInputGetKeystroke(  
         DWORD dwUserIndex,  
         _Reserved_ dwReserved,  
         XINPUT_KEYSTROKE* pKeystroke  
)  
```

### 参数

*dwUserIndex*   \_In\_\
类型：DWORD

与设备关联的已登录玩家的索引。取值范围为 0 到 XUSER\_MAX\_COUNT - 1；XUSER\_INDEX\_ANY 用于从任意用户获取下一个可用的输入事件。

*dwReserved*   \
类型：*Reserved*

此参数未使用。

*pKeystroke*   \_Out\_\
类型：[XINPUT\_KEYSTROKE\*](/reference/input/xinputongameinput/structs/xinput_keystroke)

指向 [XINPUT\_KEYSTROKE](/reference/input/xinputongameinput/structs/xinput_keystroke) 结构的指针，用于接收输入事件。

### 返回值

类型：DWORD

* 如果函数成功，将返回 **ERROR\_SUCCESS**。
* 如果没有按下新按键，函数将返回 **ERROR\_EMPTY**。
* 如果未连接控制器，或者用户尚未激活它，函数将返回 **ERROR\_DEVICE\_NOT\_CONNECTED**；请参阅下方的“备注”部分。
* 如果函数失败，将返回 Winerror.h 中定义的错误代码。

## 备注

无线控制器在系统启动时不被视为已激活；如果在无线控制器激活之前调用任何 XInput 函数，该调用将返回 **ERROR\_DEVICE\_NOT\_CONNECTED**。游戏必须检查返回码，并做好处理此情况的准备。有线控制器在插入时会自动激活。当用户按下 START 或 Guide 按钮以打开控制器时，无线控制器即被激活。

如果从 XInput 移植到 GameInput 的代码不调用 GetKeyStroke 函数，则可以通过定义 XINPUT\_ON\_GAMEINPUT\_NO\_XINPUTGETKEYSTROKE 来减小 XInput 包装器的大小。有关详细信息，请参阅 [从 XInput 移植到 GameInput](/build/core-features/common/input/porting/input-porting-xinput#optimizingSection)。

## 要求

**头文件：** XInputOnGameInput.h

**库：** xgameruntime.lib

**支持的平台：** XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[将 XInput 移植到 GameInput](/build/core-features/common/input/porting/input-porting-xinput)\
[XInputOnGameInput](/reference/input/xinputongameinput/xinputongameinput_members)


## Related topics

- [XINPUT_KEYSTROKE](/zh-CN/reference/input/xinputongameinput/structs/xinput_keystroke.md)
- [XInputOnGameInput](/zh-CN/reference/input/xinputongameinput/xinputongameinput_members.md)
- [从 XInput 移植到 GameInput](/zh-CN/build/core-features/common/input/porting/input-porting-xinput.md)
- [XInputGetCapabilities](/zh-CN/reference/input/xinputongameinput/functions/xinputgetcapabilities.md)
- [XInputGetState](/zh-CN/reference/input/xinputongameinput/functions/xinputgetstate.md)