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

# RegisterSystemButtonCallback（已弃用）

> 为 Guide 和 Share 按钮注册回调（已在 v4 中移除）。

> [!WARNING]
>
> **已弃用。** 此方法已在 GameInput v4 中移除，当前 API 中不再提供。请改为使用 [IGameInputReading::GetSystemButtonState](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsystembuttonstate.md) 和 `GameInputKindSystemButton` 从输入读数中读取系统按钮状态。

注册一个回调函数，在按下或释放 Guide 或 Share 按钮时调用。

## 语法

```cpp theme={null}
HRESULT RegisterSystemButtonCallback(
    IGameInputDevice* device,
    GameInputSystemButtons buttonFilter,
    void* context,
    GameInputSystemButtonCallback callbackFunc,
    GameInputCallbackToken* callbackToken
);
```

### 参数

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

可选，将注册的回调限定为由特定设备触发。

*buttonFilter*   \_In\_\
类型：GameInputSystemButtons

要接收回调的按钮集合，以逻辑 OR 组合。

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

为回调函数提供相关信息的对象。通常为调用对象。

*callbackFunc*   \_In\_\
类型：GameInputSystemButtonCallback

由标题定义、在按下或释放系统按钮时调用的回调函数。

*callbackToken*   \_Out\_opt\_\
类型：GameInputCallbackToken\*

标识已注册回调函数的令牌。如果需要取消或注销回调函数，可使用此令牌来标识已注册的函数。

### 返回值

类型：HRESULT

函数结果。

## 备注

此方法注册一个在按下或释放 Guide 或 System 按钮时调用的回调函数。是否分发回调取决于你的进程和其他进程中通过 [IGameInput::SetFocusPolicy](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_setfocuspolicy.md) 设置的 [GameInputFocusPolicy](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputfocuspolicy.md)。有关详细信息，请参阅 [GameInputFocusPolicy](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/enums/gameinputfocuspolicy.md)。在 XBOX 上，系统外壳始终会使用 Guide 按钮，因此这些回调在 XBOX 上永远不会被分发。

在 PC 上，当 GameInput 运行时随应用程序旁加载而不是安装在系统上时，此方法将失败并返回 `GAMEINPUT_E_FEATURE_REQUIRES_INSTALL` (0x838AD02B)。有关详细信息，请参阅 [GameInput 旁加载](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-agility-redistributable.md)。

若要停止接收回调，请参阅 [IGameInput::UnregisterCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_unregistercallback.md) 和 [IGameInput::StopCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_stopcallback.md) 方法。

此方法已添加到 Windows SDK 10.0.26031 预览版的 GameInput.h 中，将添加到 GDK 的未来版本。

以下代码示例演示如何侦听 Guide 按钮的按下事件。

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

void CALLBACK OnGuideButton(
    _In_ GameInputCallbackToken callbackToken,
    _In_ void * context,
    _In_ IGameInputDevice * device,
    _In_ uint64_t timestamp,
    _In_ GameInputSystemButtons currentButtons,
    _In_ GameInputSystemButtons previousButtons)
{
    bool guidePressed = currentButtons & GameInputSystemButtons::GameInputSystemButtonGuide;
    bool guidePreviouslyPressed = previousButtons & GameInputSystemButtons::GameInputSystemButtonGuide;
    if (guidePressed && !guidePreviouslyPressed)
    {
        // Handle new Guide button press
    }
    else if (!guidePressed && guidePreviouslyPressed)
    {
        // Handle new Guide button release
    }
}

void RegisterForGuideButton() noexcept
{
    GameInputCallbackToken token;
    if (SUCCEEDED(gameInput->RegisterSystemButtonCallback(
        nullptr, // All devices
        GameInputSystemButtons::GameInputSystemButtonGuide, // Filter to the Guide button
        nullptr, // No context
        OnGuideButton, // Callback
        &token))) // token
    {
        // Success!
    }
}
```

## 要求

**头文件：** GameInput.h

**库：** gameinput.lib

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

## 另请参阅

[已弃用的 GameInput API 成员](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)\
[IGameInputReading::GetSystemButtonState](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsystembuttonstate.md)\
[GameInput 高级主题](https://docs.xbox.com/zh-CN/build/core-features/common/input/advanced/input-advanced-topics.md)\

[GameInput 概述](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-overview.md)\

[IGameInput](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/igameinput.md)

## 版本历史

| 版本 | 变更 |
| - | - |
| **v4** | 已移除。 |
| **v1** | 引入。取代 `RegisterGuideButtonCallback`。 |


## Related topics

- [IGameInput::RegisterGuideButtonCallback（已弃用）](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_registerguidebuttoncallback.md)
- [GameInputGuidButtonCallback（已弃用）](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/functions/gameinputguidebuttoncallback.md)
- [IGameInput::RegisterKeyboardLayoutCallback（已弃用）](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_registerkeyboardlayoutcallback.md)
- [IGameInput::StopCallback（已弃用）](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_stopcallback.md)
- [已弃用的 GameInput API 成员](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)