> ## 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](/zh-TW/reference/input/gameinput/enums/gameinputkind)

將已註冊的回呼限制為只針對至少支援其中一種指定輸入類型的裝置觸發。

*statusFilter*   \_In\_\
類型：[GameInputDeviceStatus](/zh-TW/reference/input/gameinput/enums/gameinputdevicestatus)

將已註冊的回呼限制為只針對特定類型的裝置狀態變更觸發。

*enumerationKind*   \_In\_\
類型：[GameInputEnumerationKind](/zh-TW/reference/input/gameinput/enums/gameinputenumerationkind)

決定是否列舉裝置，以及函式是否會等待列舉完成。

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

為回呼函式提供相關資訊的某個物件。通常是呼叫端物件。

*callbackFunc*   \_In\_\
類型：[GameInputDeviceCallback](/zh-TW/reference/input/gameinput/functions/gameinputdevicecallback)

要針對裝置連線或中斷連線事件註冊的遊戲定義回呼。

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

識別已註冊回呼函式的權杖。當您需要取消或取消註冊回呼函式時，會使用此權杖來識別已註冊的函式。

### 傳回值

類型：HRESULT

函式結果。

## 備註

由 **IGameInput::RegisterDeviceCallback** 註冊的函式可用來回應裝置的狀態變更，例如連線或中斷連線。可辨識的狀態變更類型列於 [GameInputDeviceStatus](/zh-TW/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 概觀](/zh-TW/build/core-features/common/input/overviews/input-overview)\
[IGameInput](/zh-TW/reference/input/gameinput/interfaces/igameinput/igameinput)\
[IGameInput::UnregisterCallback](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_unregistercallback)\
[IGameInput::StopCallback](/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_stopcallback)

## 版本歷程記錄

| 版本 | 變更 |
| - | - |
| **v0** | 已推出。 |


## Related topics

- [IGameInput::RegisterDeviceCallback](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerdevicecallback.md)
- [GameInputDeviceCallback](/reference/input/gameinput/functions/gameinputdevicecallback.md)
- [IGameInput::StopCallback](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_stopcallback.md)