> ## 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 (例如，使用搭配 `CP_UTF8` 的 `MultiByteToWideChar`)。

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-TW/reference/input/gameinput/deprecated/interfaces/igameinputdevice/methods/igameinputdevice_getdeviceinfo.md) 所傳回 [GameInputDeviceInfo](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/structs/gameinputdeviceinfo.md) 結構的 `pnpPath` 成員取得。

## 需求

**標頭：** GameInput.h

**程式庫：** gameinput.lib

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

## 另請參閱

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

## 版本歷程記錄

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


## Related topics

- [IGameInputDevice::GetDisplayName](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdisplayname.md)
- [IGameInputDevice::GetContainerId](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getcontainerid.md)
- [GameInput 常見問題集](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-faq.md)
- [將 GameInput 與現有的輸入堆疊結合使用](https://docs.xbox.com/zh-TW/build/core-features/common/input/porting/input-porting.md)
- [IGameInputDevice::GetDeviceFamily](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdevicefamily.md)