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

# GameInput コールバック

> GameInput コールバック

<a id="introductionSection" />

`GameInput` は主にポーリングモデルを中心に設計されていますが、アプリケーションに非同期で通知することが最適な場合もあります。これをサポートするため、[IGameInput](/reference/input/gameinput/interfaces/igameinput/igameinput) インターフェイスは、対象となる特定のイベントが発生したときに呼び出されるコールバック関数を登録するためのいくつかのメソッドを公開しています。

内部的に、`GameInput` はコールバックのディスパッチをシリアル化し、一度に 1 つのコールバックのみが実行されるようにします。`GameInput` は、コールバックが時系列順にディスパッチされることを保証します。これらの保証により、アプリケーションがコールバック関数内に記述する必要のあるコードが簡素化されます。

`GameInput` は、種類にかかわらず、任意の時点で最大 64 個のコールバックを登録できます。コールバックは `GameInput` の内部ワーカースレッドからディスパッチされます。この動作の詳細、およびこの作業を手動でスケジュールするオプションについては、[GameInput ワークキュー](/build/core-features/common/input/advanced/input-work-queues) を参照してください。

<a id="deviceCallbacksSection" />

## デバイスコールバック

デバイスコールバックは、次の構文に示すように、入力デバイスの状態が変化したことをアプリケーションに知らせる方法を提供します。最も一般的には、デバイスの接続と切断を検出するために使用されますが、その他の状態変化も対象となる場合があります。

```c++ theme={null}
HRESULT RegisterDeviceCallback(
    _In_opt_ IGameInputDevice * device,
    _In_ GameInputKind inputKind,
    _In_ GameInputDeviceStatus statusFilter,
    _In_ GameInputEnumerationKind enumerationKind,
    _In_opt_ void * context,
    _In_ GameInputDeviceCallback callbackFunc,
    _Out_opt_ _Result_zeroonfailure_ GameInputCallbackToken * callbackToken);
```

デバイスコールバックは、いくつかのオプションのフィルターを指定して登録できます。これには、特定の種類の入力を生成するデバイスへのフィルタリング、特定の状態変化へのフィルタリング、特定のデバイスへのフィルタリング、またはそれらのフィルターの任意の組み合わせが含まれます。たとえば、アプリケーションはデバイスがシステムから切断されたときに通知するコールバックを設定できます。

デバイスの状態変化に加えて、[RegisterDeviceCallback](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerdevicecallback) メソッドはデバイス列挙にも使用できます。`enumerationKind` パラメーターは [GameInputEnumerationKind](/reference/input/gameinput/enums/gameinputenumerationkind) 列挙型の値を受け取り、列挙をコールバック登録の一部として行うかどうか、そしてその場合はブロッキング方式と非同期方式のどちらで行うかを示します。デバイス列挙とその後の状態変化を単一のアトミック操作に組み合わせることで、多くのアプリケーションが入力コード内で意図せず被る競合状態を回避できます。

<a id="readingCallbacksSection" />

## 読み取りコールバック

読み取りコールバックを使用すると、次の構文に示すように、新しい読み取りが入力ストリームに到着したときにアプリケーションに通知できます。多くのアプリケーションでは入力をポーリングする方が適していますが、イベント駆動型入力の方が望ましい状況もあります。たとえば、ゲームのメインメニュー UI はイベントベースの入力の方が適している可能性があります。もう 1 つの例は、ユーザーに選択を促した後に入力を待つ必要がある入力マッピング UI です。

```c++ theme={null}
HRESULT RegisterReadingCallback(
    _In_opt_ IGameInputDevice * device,
    _In_ GameInputKind inputKind,
    _In_ float analogThreshold,
    _In_opt_ void * context,
    _In_ GameInputReadingCallback callbackFunc,
    _Out_opt_ _Result_zeroonfailure_ GameInputCallbackToken * callbackToken);
```

デバイスコールバックと同様に、読み取りコールバックにもいくつかのオプションのフィルターを指定して登録できます。アプリケーションは入力ストリームからの特定の読み取りのサブセットに関心を持つことがあるため、これは特に読み取りコールバックにとって有用です。[RegisterReadingCallback](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerreadingcallback) メソッドでは、特定の種類の入力を生成するデバイスへのフィルタリング、および/または特定のデバイスの入力へのフィルタリングが可能です。

アプリケーションは、コールバックが発火する前に一定の最小限の動きを必要とするアナログ入力値 (ゲームパッドのサムスティックなど) のフィルターを指定することもできます。これにより、高解像度のアナログ状態の変化が必要でない場合、コールバックの頻度を大幅に減らすことができます。良い例として、ユーザーに選択を促した後に入力の変化を待つ入力マッピング UI の実装があります。

<a id="unregisteringSection" />

## コールバックの登録解除

コールバックが正常に登録された後、アプリケーションはコールバックの実行に必要なリソースが有効なまま保持されることを保証する必要があります。これには、コールバックのコードが使用するリソースと、コールバック関数自体の両方が含まれます。たとえば、アプリケーションが必要に応じてロードおよびアンロードする DLL 内にコールバック関数がホストされている場合などです。

これらのリソースを安全に再要求するには、アプリケーションはまず、`Register*Callback` メソッドから受け取ったトークンを [UnregisterCallback](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_unregistercallback) メソッドに渡してコールバックの登録を解除する必要があります。このメソッドが呼び出されたときにコールバックが実行されている場合、コールバックの実行が完了するまでブロックされます。その結果、コールバックが自身のコールバック関数内から自身の登録を解除することはできません。

コールバックは、[StopCallback](/reference/input/gameinput/interfaces/igameinput/methods/igameinput_stopcallback) メソッドを呼び出すことで停止することもできます。これはコールバックを登録解除しませんが、コールバックが再度呼び出されないようにします。コールバックが登録解除されないため、このメソッドはコールバック自身のコールバック関数内から安全に呼び出すことができます。現在のコールバックの実行を完了しますが、それを再度呼び出しません。同時に許可されるコールバックは 64 個のみであるため、コールバックは最終的には登録解除する必要があります。

<a id="seeAlsoSection" />

## リファレンス API ドキュメント

* [GameInput (API 内容)](/reference/input/gameinput/gameinput_members)

## 関連項目

[GameInput の基礎](/build/core-features/common/input/overviews/input-fundamentals)

[GameInput の高度なトピック](/build/core-features/common/input/advanced/input-advanced-topics)

[Input API リファレンス](/reference/input/gc-reference-input-toc)


## Related topics

- [GameInput の高度なトピック: フォース フィードバックとコールバック](/ja-jp/build/core-features/common/input/advanced/index.md)
- [GameInputEnumerationKind](/ja-jp/reference/input/gameinput/enums/gameinputenumerationkind.md)
- [GameInput の高度なトピック](/ja-jp/build/core-features/common/input/advanced/input-advanced-topics.md)
- [Game Saves の UI コールバック](/ja-jp/services/playfab/player-progression/game-saves/ui-callbacks.md)
- [方法: コールバックの送信](/ja-jp/build/core-features/common/async/async-task-queue-design-howto/submitting-callbacks.md)