Метод IShellFolder::GetDisplayNameOf (shobjidl_core.h)

Статья
08/26/2023

Извлекает отображаемое имя для указанного объекта файла или вложенной папки.

Синтаксис

HRESULT GetDisplayNameOf(
  [in]  PCUITEMID_CHILD pidl,
  [in]  SHGDNF          uFlags,
  [out] STRRET          *pName
);

Параметры

[in] pidl

Тип: PCUITEMID_CHILD

PIDL, однозначно идентифицирующий объект файла или вложенную папку относительно родительской папки.

[in] uFlags

Тип: SHGDNF

Флаги, используемые для запроса типа возвращаемого отображаемого имени. Список возможных значений см. в описании перечисленного типа SHGDNF .

[out] pName

Тип: STRRET*

При возврате этим методом содержит указатель на структуру STRRET , в которой возвращается отображаемое имя. Тип имени, возвращаемого в этой структуре, может быть запрошенным, но папка оболочки может возвращать другой тип.

Возвращаемое значение

Тип: HRESULT

Если этот метод завершается успешно, он возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Обычно pidl может ссылаться только на элементы, содержащиеся в родительской папке. PIDL должен быть одноуровневый и содержать ровно одну структуру SHITEMID , за которой следует завершающий ноль. Если вы хотите получить отображаемое имя элемента, который находится глубже, чем на один уровень от родительской папки, используйте SHBindToParent для привязки к непосредственной родительской папке элемента, а затем передайте одноуровневый PIDL элемента в IShellFolder::GetDisplayNameOf.

Кроме того, если флаг SHGDN_FORPARSING задан в uFlags , а флаг SHGDN_INFOLDER не задан, pidl может ссылаться на объект на любом уровне ниже родительской папки в иерархии пространства имен. Одновременно pidl может быть многоуровневым PIDL относительно родительской папки и содержать несколько структур SHITEMID . Однако это больше не поддерживается, и pidl теперь должен ссылаться только на один дочерний элемент.

Самый простой способ получить отображаемое имя из структуры, на которую указывает pName , — передать его в StrRetToBuf или StrRetToStr. Эти функции принимают структуру STRRET и возвращают имя. Вы также можете проверить элемент uType структуры и получить имя из соответствующего элемента.

Флаги, указанные в uFlags , являются подсказками о предполагаемом использовании имени. Они не гарантируют, что IShellFolder вернет запрошенную форму имени. Если эта форма недоступна, может быть возвращена другая форма. В частности, нет никакой гарантии, что имя, возвращаемое флагом SHGDN_FORPARSING , будет успешно проанализировано iShellFolder::P arseDisplayName. Существуют также некоторые сочетания флагов, которые могут привести к тому, что круговой путь GetDisplayNameOf/ParseDisplayName не возвращает исходный список идентификаторов. Это исключительное явление, но вы должны проверка, чтобы быть уверенным.

Примечание Имя синтаксического анализа, которое возвращается, если в uFlags установлен флаг SHGDN_FORPARSING , не обязательно является обычной текстовой строкой. Виртуальные папки, такие как "Мой компьютер", могут возвращать строку, содержащую ИДЕНТИФИКАТОР GUID объекта папки в формате "::{GUID}". Разработчикам, реализующим IShellFolder::GetDisplayNameOf , рекомендуется возвращать имена синтаксического анализа, максимально близкие к отображаемым именам, так как пользователю часто требуется ввести или изменить эти имена.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	shobjidl_core.h (включая Shobjidl.h)
DLL	Shell32.dll (версия 4.0 или более поздняя)

См. также раздел

IShellFolder

IShellFolder2

Поделиться через