> ## 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/zh-CN/reference/input/gameinput/functions/gameinputcreate.md) 类似，但它接受你所需 `IGameInput` 版本的 IID。这两个函数返回的都是同一个每进程单一实例上的接口。第一次调用会创建该单一实例，之后的调用会为其添加引用。有关何时调用这些函数以及应保留引用多长时间的指导，请参阅 [GameInputCreate](https://docs.xbox.com/zh-CN/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-CN/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-CN/reference/input/gameinput/functions/gameinputcreate.md)\
[GameInput API 版本管理](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-versioning.md)\
[在一个应用程序中使用多个 GameInput API 版本](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInput](https://docs.xbox.com/zh-CN/reference/input/gameinput/gameinput_members.md)

## 版本历史

| 版本 | 变更 |
| - | - |
| **v3** | 引入。 |


## Related topics

- [GameInputCreate](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputcreate.md)
- [GameInput API 成员](https://docs.xbox.com/zh-CN/reference/input/gameinput/gameinput_members.md)
- [XBOX 主机上的 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-xbox.md)
- [在一个应用程序中使用多个 GameInput API 版本](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-version-interop.md)
- [XInputOnGameInputInitialize](https://docs.xbox.com/zh-CN/reference/input/xinputongameinput/functions/xinputongameinputinitialize.md)