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

# GameInputInitialize

> 特定の GameInput API バージョンの IGameInput インターフェイスのインスタンスを取得します。

特定の GameInput API バージョンの `IGameInput` インターフェイスのインスタンスを取得します。

## 構文

```cpp theme={null}
HRESULT GameInputInitialize(
    REFIID riid,
    LPVOID* ppv
);
```

### パラメーター

*riid*   \_In\_\
型: REFIID

取得する `IGameInput` インターフェイスのインターフェイス ID (IID)。IID によって GameInput API のバージョンが選択されます。たとえば、v4 の場合は `__uuidof(GameInput::v4::IGameInput)`、v0 の場合は `__uuidof(GameInput::v0::IGameInput)` を指定します。

*ppv*   \_COM\_Outptr\_\
型: LPVOID\*

基になるプロセスごとのシングルトンの、要求されたインターフェイスを受け取ります。関数が失敗した場合は `nullptr` に設定されます。

### 戻り値

型: HRESULT

成功した場合は `S_OK` を返します。*riid* が `IGameInput` インターフェイスの IID でない場合、またはインストールされている GameInput ランタイムが要求された API バージョンをサポートしていない場合は、`E_NOINTERFACE` を返します。GameInput ランタイムを読み込めない場合は、その他のエラー コードを返します。

## 解説

`GameInputInitialize` は [GameInputCreate](https://docs.xbox.com/ja-jp/reference/input/gameinput/functions/gameinputcreate.md) と同様に動作しますが、目的の `IGameInput` バージョンの IID を受け取ります。どちらの関数も、同じプロセスごとのシングルトンのインターフェイスを返します。最初の呼び出しでシングルトンが作成され、以降の呼び出しではそのシングルトンへの参照が追加されます。これらの関数を呼び出すタイミングと参照を保持する期間に関するガイダンスについては、[GameInputCreate](https://docs.xbox.com/ja-jp/reference/input/gameinput/functions/gameinputcreate.md) を参照してください。

GameInput ランタイムは、自身のメジャー バージョン以下のすべての API バージョンをサポートします。たとえば、GameInput 4.0 ランタイムは、v0 から v4 までの任意の `IGameInput` バージョンの IID を受け付けます。インストールされているランタイムよりも新しいバージョンを要求すると、関数は `E_NOINTERFACE` で失敗します。これを利用して、より新しい API バージョンが利用可能かどうかを実行時に確認できます。

### GameInputCreate との関係

v3 以降、GameInput ヘッダーの `GameInputCreate` はインライン関数であり、ヘッダーで宣言されている `IGameInput` インターフェイスの IID を指定して `GameInputInitialize` を呼び出します。

```cpp theme={null}
inline HRESULT GameInputCreate(
    _COM_Outptr_ IGameInput** gameInput)
{
    return GameInputInitialize(
        IID_IGameInput,
        reinterpret_cast<void**>(gameInput));
}
```

このため、v3 以降で `GameInputCreate` を呼び出すと、インクルードしたヘッダーに対応するバージョンの `IGameInput` が作成されます。ヘッダーをインクルードせずに別のバージョンを作成するには、`GameInputInitialize` を直接呼び出します。

v0 では、`GameInputCreate` は `GameInput.lib` によってエクスポートされる関数であり、常に v0 インターフェイスを作成します。[Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet パッケージに含まれる `GameInput.lib` は、代わりに `GameInputInitialize` をエクスポートします。そのライブラリをリンクする場合に v0 インターフェイスを作成するには、v0 の IID を指定して `GameInputInitialize` を呼び出します。v0 ヘッダーでは `GameInputInitialize` が宣言されていないため、自分で宣言してください。

```cpp theme={null}
#include <v0/GameInput.h>

STDAPI GameInputInitialize(_In_ REFIID riid, _COM_Outptr_ LPVOID* ppv);

HRESULT CreateLegacyGameInput(IGameInput** gameInput)
{
    return GameInputInitialize(__uuidof(IGameInput), reinterpret_cast<void**>(gameInput));
}
```

インストールされているランタイムが古すぎて `GameInputInitialize` を提供していない場合、ライブラリは v0 の IID についてはランタイムの `GameInputCreate` にフォールバックし、それ以外の IID については `E_NOINTERFACE` を返します。

既に取得済みの `IGameInput` オブジェクトの別の API バージョンを取得するには、`GameInputInitialize` を再度呼び出すのではなく、そのオブジェクトに対して `QueryInterface` を呼び出します。詳細と例については、「[1 つのアプリケーションで複数の GameInput API バージョンを使用する](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-version-interop.md)」を参照してください。

## 要件

**ヘッダー:** GameInput.h

**ライブラリ:** GameInput.lib

**サポートされているプラットフォーム:** Windows、XBOX One ファミリー本体、XBOX Series 本体

## 関連項目

[GameInputCreate](https://docs.xbox.com/ja-jp/reference/input/gameinput/functions/gameinputcreate.md)\
[GameInput API のバージョン管理](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-versioning.md)\
[1 つのアプリケーションで複数の GameInput API バージョンを使用する](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInput](https://docs.xbox.com/ja-jp/reference/input/gameinput/gameinput_members.md)

## バージョン履歴

| バージョン | 変更内容 |
| - | - |
| **v3** | 導入されました。 |


## Related topics

- [GameInputCreate](https://docs.xbox.com/ja-jp/reference/input/gameinput/functions/gameinputcreate.md)
- [XBOX 本体での GameInput](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-xbox.md)
- [1 つのアプリケーションで複数の GameInput API バージョンを使用する](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-version-interop.md)
- [GameInput API メンバー](https://docs.xbox.com/ja-jp/reference/input/gameinput/gameinput_members.md)
- [XInputOnGameInputInitialize](https://docs.xbox.com/ja-jp/reference/input/xinputongameinput/functions/xinputongameinputinitialize.md)