> ## 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` 介面的介面識別碼 (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/zh-TW/reference/input/gameinput/functions/gameinputcreate.md) 相同，但會接受您所需 `IGameInput` 版本的 IID。這兩個函式都會傳回同一個個別處理序單一執行個體上的介面。第一次呼叫會建立單一執行個體，之後的呼叫則會為其新增參考。如需何時呼叫這些函式以及參考應保留多久的指引，請參閱 [GameInputCreate](https://docs.xbox.com/zh-TW/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 版本，請在該物件上呼叫 `QueryInterface`，而不要再次呼叫 `GameInputInitialize`。如需詳細資訊和範例，請參閱[在單一應用程式中使用多個 GameInput API 版本](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-version-interop.md)。

## 需求

**標頭：** GameInput.h

**程式庫：** GameInput.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[GameInputCreate](https://docs.xbox.com/zh-TW/reference/input/gameinput/functions/gameinputcreate.md)\
[GameInput API 版本控制](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-versioning.md)\
[在單一應用程式中使用多個 GameInput API 版本](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInput](https://docs.xbox.com/zh-TW/reference/input/gameinput/gameinput_members.md)

## 版本歷程記錄

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


## Related topics

- [GameInputCreate](https://docs.xbox.com/zh-TW/reference/input/gameinput/functions/gameinputcreate.md)
- [GameInput API 成員](https://docs.xbox.com/zh-TW/reference/input/gameinput/gameinput_members.md)
- [XBOX 主機上的 GameInput](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-xbox.md)
- [在單一應用程式中使用多個 GameInput API 版本](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-version-interop.md)
- [XInputOnGameInputInitialize](https://docs.xbox.com/zh-TW/reference/input/xinputongameinput/functions/xinputongameinputinitialize.md)