> ## 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::GetDisplayName

> 以 UTF-8 字串形式取得輸入裝置的易記顯示名稱。

以 UTF-8 字串形式取得輸入裝置的易記顯示名稱。

## 語法

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

### 參數

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

*buffer* 所指向之緩衝區的大小 (以位元組為單位)。傳遞 0 以查詢所需的大小。

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

接收以 Null 結尾之 UTF-8 顯示名稱的緩衝區。傳遞 `nullptr` 以查詢所需的大小。

### 傳回值

類型：uint32\_t

容納顯示名稱所需的緩衝區大小 (以位元組為單位)，包括 Null 結束字元。

## 備註

只有在 *buffer* 不是 `nullptr` 且 *bufferByteCount* 大於或等於所需的大小時，此方法才會將顯示名稱寫入 *buffer*。否則，緩衝區不會遭到修改。若要擷取顯示名稱，請先以 0 的 *bufferByteCount* 和 `nullptr` 的 *buffer* 呼叫此方法一次以取得所需的大小，配置該大小的緩衝區，然後再次呼叫此方法。

如果裝置沒有顯示名稱，所需的大小為 1，且此方法會寫入空字串。

顯示名稱是裝置的「易記」名稱。您可以在應用程式的 UI 中顯示它，但無法保證它已當地語系化。GameInput 會在數個位置搜尋此字串，而最終的後援來源之一是裝置的韌體。

顯示名稱在裝置物件的存留期間內不會變更。

下列範例會擷取裝置的顯示名稱。

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

    std::vector<char> buffer(size);
    device->GetDisplayName(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) 結構的 `displayName` 成員取得。

## 需求

**標頭：** 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::GetPnpPath](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getpnppath.md)

## 版本歷程記錄

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


## Related topics

- [IGameInputDevice::GetPnpPath](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getpnppath.md)
- [IGameInputDevice::GetDeviceFamily](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdevicefamily.md)
- [IGameInputDevice::GetDeviceId](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdeviceid.md)
- [IGameInputDevice::GetXInputDeviceIndex](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getxinputdeviceindex.md)
- [IGameInputDevice::GetUsage](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getusage.md)