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

# IGameInput::RegisterDeviceCallback

> IGameInput::RegisterDeviceCallback

# IGameInput::RegisterDeviceCallback

注册一个 GameInputDeviceCallback 函数，以便在每当有设备连接到系统或从系统断开连接时被调用。还允许在设备属性发生变化时调用该函数。

## 语法

```cpp theme={null}
HRESULT RegisterDeviceCallback(
    IGameInputDevice* device,
    GameInputKind inputKind,
    GameInputDeviceStatus statusFilter,
    GameInputEnumerationKind enumerationKind,
    void* context,
    GameInputDeviceCallback callbackFunc,
    GameInputCallbackToken* callbackToken
);
```

### 参数

*device*   \_In\_opt\_\
类型：IGameInputDevice\*

将已注册的回调限制为仅对特定设备触发。

*inputKind*   \_In\_\
类型：[GameInputKind](/reference/input/gameinput/enums/gameinputkind)

将已注册的回调限制为仅针对支持至少一种指定输入类型的设备触发。

*statusFilter*   \_In\_\
类型：[GameInputDeviceStatus](/reference/input/gameinput/enums/gameinputdevicestatus)

将已注册的回调限制为仅针对特定类型的设备状态更改触发。

*enumerationKind*   \_In\_\
类型：[GameInputEnumerationKind](/reference/input/gameinput/enums/gameinputenumerationkind)

确定是否枚举设备以及该函数是否会等待枚举完成。

*context*   \_In\_opt\_\
类型：void\*

一些为回调函数提供相关信息的对象。通常是调用对象本身。

*callbackFunc*   \_In\_\
类型：[GameInputDeviceCallback](/reference/input/gameinput/functions/gameinputdevicecallback)

要为设备连接或断开事件注册的、由游戏标题定义的回调。

*callbackToken*   \_Result\_zeroonfailure\_\
类型：GameInputCallbackToken\*

用于标识已注册回调函数的令牌。当你需要取消或取消注册该回调函数时，此令牌用于标识已注册的函数。

### 返回值

类型：HRESULT

函数结果。

## 备注

通过 **IGameInput::RegisterDeviceCallback** 注册的函数可用于响应设备状态的变化，例如连接或断开连接。可识别的状态更改类型列在 [GameInputDeviceStatus](/reference/input/gameinput/enums/gameinputdevicestatus) 中。

*enumerationKind* 参数可用于生成初始的一批回调——为连接到系统的每个设备生成一个回调。此初始枚举可设置为异步或同步枚举。同步枚举将在 **IGameInput::RegisterDeviceCallback** 返回之前调用所有初始回调。

以下 C++ 示例演示了如何显式枚举已连接的游戏手柄和键盘。

```cpp theme={null}
Microsoft::WRL::ComPtr<IGameInput> gameInput;

void CALLBACK OnDeviceEnumerated(
    _In_ GameInputCallbackToken callbackToken,
    _In_ void * context,
    _In_ IGameInputDevice * device,
    _In_ uint64_t timestamp,
    _In_ GameInputDeviceStatus currentStatus,
    _In_ GameInputDeviceStatus previousStatus)
{
    // Application-specific code to handle the enumerated device
}

void EnumerateDevicesWorker() noexcept
{
    GameInputCallbackToken token;
    if (SUCCEEDED(gameInput->RegisterDeviceCallback(
        nullptr,                                      // Don't filter to events from a specific device
        GameInputKindGamepad | GameInputKindKeyboard, // Enumerate gamepads and keyboards
        GameInputDeviceAnyStatus,                     // Any device status
        GameInputBlockingEnumeration,                 // Enumerate synchronously
        nullptr,                                      // No callback context parameter
        OnDeviceEnumerated,                           // Callback function
        &token)))                                     // Generated token
    {
        gameInput->UnregisterCallback(token, 5000);
    }
}
```

以下 C++ 示例演示了如何在设备连接或断开连接时接收通知。

```cpp theme={null}
Microsoft::WRL::ComPtr<IGameInput> gameInput;

void CALLBACK OnDeviceConnectionChanged(
    _In_ GameInputCallbackToken callbackToken,
    _In_ void * context,
    _In_ IGameInputDevice * device,
    _In_ uint64_t timestamp,
    _In_ GameInputDeviceStatus currentStatus,
    _In_ GameInputDeviceStatus previousStatus,
    )
{
    if (currentStatus & GameInputDeviceConnected)
    {
        // Application-specific code to handle the device connection
    }
    else
    {
        // Application-specific code to handle the device disconnection
    }
}

void MonitorDeviceConnectionChanges(
    _In_ volatile bool & cancelMonitoring) noexcept
{
    GameInputCallbackToken token;
    if (SUCCEEDED(gameInput->RegisterDeviceCallback(
        nullptr,                                      // Don't filter to events from a specific device
        GameInputKindGamepad | GameInputKindKeyboard, // Listen for Gamepad and Keyboard changes
        GameInputDeviceConnected,                     // Notify on changes to GameInputDeviceConnected status
        GameInputAsyncEnumeration,                    // Enumerate initial devices asynchronously
        nullptr,                                      // No callback context parameter
        OnDeviceConnectionChanged,                    // Callback function
        &token)))                                     // Generated token
    {
        while (!cancelMonitoring)
        {
            Sleep(100);
        }

        gameInput->UnregisterCallback(token, 5000);
    }
}
```

## 要求

[输入 API 概述](/build/core-features/common/input/overviews/input-overview)\
[IGameInput](/reference/input/gameinput/interfaces/igameinput/igameinput)\
[IGameInput::UnregisterCallback](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_unregistercallback)\
[IGameInput::StopCallback](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_stopcallback)

## 版本历史

| 版本     | 变更  |
| ------ | --- |
| **v0** | 引入。 |


## Related topics

- [IGameInput::StopCallback](/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_stopcallback.md)
- [GameInputDeviceCallback](/zh-CN/reference/input/gameinput/functions/gameinputdevicecallback.md)
- [IGameInput::UnregisterCallback](/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_unregistercallback.md)
- [GameInputDeviceStatus](/zh-CN/reference/input/gameinput/enums/gameinputdevicestatus.md)
- [GameInputEnumerationKind](/zh-CN/reference/input/gameinput/enums/gameinputenumerationkind.md)