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

# IGameInputDevice::GetPnpPath

> 以 UTF-8 字符串形式获取输入设备的即插即用设备路径。

以 UTF-8 字符串形式获取输入设备的即插即用 (PnP) 设备路径。

## 语法

```cpp theme={null}
uint32_t GetPnpPath(
    uint32_t bufferByteCount,
    char* buffer
);
```

### 参数

*bufferByteCount*   \_In\_\
类型：uint32\_t

*buffer* 所指向的缓冲区的大小（以字节为单位）。传递 0 可查询所需的大小。

*buffer*   \_Out\_writes\_bytes\_opt\_(bufferByteCount)\
类型：char\*

接收以 null 结尾的 UTF-8 PnP 路径的缓冲区。传递 `nullptr` 可查询所需的大小。

### 返回值

类型：uint32\_t

容纳 PnP 路径所需的缓冲区大小（以字节为单位），包括 null 终止符。

## 备注

仅当 *buffer* 不为 `nullptr` 且 *bufferByteCount* 大于或等于所需大小时，该方法才会将 PnP 路径写入 *buffer*。否则，缓冲区不会被修改。若要检索该路径，请先使用值为 0 的 *bufferByteCount* 和值为 `nullptr` 的 *buffer* 调用一次该方法以获取所需大小，分配该大小的缓冲区，然后再次调用该方法。

如果设备没有 PnP 路径，则所需大小为 1，并且该方法会写入一个空字符串。

可以使用 PnP 路径通过其他 API 引用底层设备。由于该路径采用 UTF-8 编码，因此在将其传递给需要宽字符字符串的 Windows API 之前，请先将其转换为 UTF-16（例如，通过将 `MultiByteToWideChar` 与 `CP_UTF8` 一起使用）。

PnP 路径在设备对象的生存期内不会更改。

以下示例检索设备的 PnP 路径。

```cpp theme={null}
std::string GetDevicePnpPath(IGameInputDevice* device)
{
    const uint32_t size = device->GetPnpPath(0, nullptr);
    if (size == 0)
    {
        return {};
    }

    std::vector<char> buffer(size);
    device->GetPnpPath(size, buffer.data());

    return std::string(buffer.data());
}
```

在 GameInput v3 及更早版本中，此信息可从 [IGameInputDevice::GetDeviceInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinputdevice/methods/igameinputdevice_getdeviceinfo.md) 返回的 [GameInputDeviceInfo](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/structs/gameinputdeviceinfo.md) 结构的 `pnpPath` 成员中获取。

## 要求

**头文件：** GameInput.h

**库：** gameinput.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[GameInput 概述](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-overview.md)\
[IGameInputDevice](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice.md)\
[IGameInputDevice::GetDisplayName](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdisplayname.md)\
[IGameInputDevice::GetContainerId](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getcontainerid.md)

## 版本历史

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


## Related topics

- [IGameInputDevice::GetDisplayName](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdisplayname.md)
- [IGameInputDevice::GetContainerId](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getcontainerid.md)
- [GameInput 常见问题](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-faq.md)
- [将 GameInput 与现有输入堆栈结合](https://docs.xbox.com/zh-CN/build/core-features/common/input/porting/input-porting.md)
- [IGameInputDevice::GetDeviceFamily](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdevicefamily.md)