> ## 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-TW/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 或系統按鈕時呼叫的回呼函式。是否會分派回呼，取決於您的處理序與其他處理序中由 [IGameInput::SetFocusPolicy](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_setfocuspolicy.md) 設定的 [GameInputFocusPolicy](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/enums/gameinputfocuspolicy.md)。如需詳細資料，請參閱 [GameInputFocusPolicy](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/enums/gameinputfocuspolicy.md)。在 XBOX 上，殼層一律會取用 Guide 按鈕，因此這些回呼永遠不會在 XBOX 上分派。

在 PC 上，當 GameInput 執行階段是隨應用程式側載而非安裝在系統上時，此方法會失敗並傳回 `GAMEINPUT_E_FEATURE_REQUIRES_INSTALL` (0x838AD02B)。如需詳細資訊，請參閱 [GameInput 側載](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-agility-redistributable.md)。

若要停止接收回呼，請參閱 [IGameInput::UnregisterCallback](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_unregistercallback.md) 和 [IGameInput::StopCallback](https://docs.xbox.com/zh-TW/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-TW/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)\
[IGameInputReading::GetSystemButtonState](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsystembuttonstate.md)\
[GameInput 進階主題](https://docs.xbox.com/zh-TW/build/core-features/common/input/advanced/input-advanced-topics.md)\

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

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

## 版本歷程記錄

| 版本 | 變更 |
| - | - |
| **v4** | 已移除。 |
| **v1** | 已推出。取代 `RegisterGuideButtonCallback`。 |


## Related topics

- [IGameInput::RegisterGuideButtonCallback (已淘汰)](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_registerguidebuttoncallback.md)
- [GameInputGuidButtonCallback (已淘汰)](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/functions/gameinputguidebuttoncallback.md)
- [RegisterSystemButtonCallback](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registersystembuttoncallback.md)
- [IGameInput::RegisterKeyboardLayoutCallback (已淘汰)](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_registerkeyboardlayoutcallback.md)
- [IGameInput::StopCallback (已淘汰)](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_stopcallback.md)