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

Статья
08/26/2023

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

Синтаксис

HRESULT ParseDisplayName(
  [in]      HWND             hwnd,
  [in]      IBindCtx         *pbc,
  [in]      LPWSTR           pszDisplayName,
  [out]     ULONG            *pchEaten,
  [out]     PIDLIST_RELATIVE *ppidl,
  [in, out] ULONG            *pdwAttributes
);

Параметры

[in] hwnd

Тип: HWND

Дескриптор окна. Клиент должен предоставить дескриптор окна, если отображается диалоговое окно или окно сообщения. В противном случае задайте для hwndзначение NULL.

[in] pbc

Тип: IBindCtx*

Необязательный элемент. Указатель на контекст привязки, используемый для передачи параметров в качестве входных и выходных данных в функцию синтаксического анализа. Эти переданные параметры часто относятся к источнику данных и задокументированы владельцами источников данных. Например, источник данных файловой системы принимает анализируемое имя (как WIN32_FIND_DATA структуру) с помощью параметра контекста STR_FILE_SYS_BIND_DATA привязки. STR_PARSE_PREFER_FOLDER_BROWSING можно передать, чтобы указать, что URL-адреса анализируются с помощью источника данных файловой системы, когда это возможно. Создайте объект контекста привязки с помощью CreateBindCtx и заполните значения с помощью IBindCtx::RegisterObjectParam. Полный список этих ключей см. в разделе Привязка ключей строк контекста.

Если данные не передаются в функцию синтаксического анализа или не получены из нее, это значение может иметь значение NULL.

[in] pszDisplayName

Тип: LPWSTR

Строка Юникода, завершающаяся нулевым значением, с отображаемым именем. Так как каждая папка оболочки определяет собственный синтаксис синтаксического анализа, форма этой строки может отличаться. Например, папка рабочего стола принимает такие пути, как "C:\My Docs\My File.txt". Он также будет принимать ссылки на элементы в пространстве имен с идентификатором GUID, связанным с ними, используя синтаксис "::{GUID}". Например, чтобы получить полный список идентификаторов для панели управления из папки рабочего стола, можно использовать следующее:

::{CLSID for Control Panel}\::{CLSID for printers folder}

[out] pchEaten

Тип: ULONG*

Указатель на значение ULONG , которое получает количество символов отображаемого имени, которое было проанализировано. Если приложению не нужны эти сведения, задайте для параметра pchEaten значение NULL, и значение не будет возвращено.

[out] ppidl

Тип: PIDLIST_RELATIVE*

При возврате этого метода содержит указатель на PIDL для объекта . Список идентификаторов возвращаемого элемента указывает элемент относительно папки синтаксического анализа. Если объект, связанный с pszDisplayName , находится в папке синтаксического анализа, возвращенный список идентификаторов элементов будет содержать только одну структуру SHITEMID . Если объект находится во вложенной папке папки синтаксического анализа, возвращенный список идентификаторов элементов будет содержать несколько структур SHITEMID . При возникновении ошибки в этом адресе возвращается значение NULL .

Если он больше не нужен, вызывающий объект отвечает за освобождение этого ресурса путем вызова CoTaskMemFree.

[in, out] pdwAttributes

Тип: ULONG*

Значение, используемое для запроса атрибутов файла. Если он не используется, ему следует присвоить значение NULL. Чтобы запросить один или несколько атрибутов, инициализируйте этот параметр флагами SFGAO , которые представляют интересующие атрибуты. При возврате будут заданы атрибуты, которые имеют значение true и были запрошены.

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

Тип: HRESULT

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

Не используйте флаг SFGAO_VALIDATE в pdwAttributes для проверки существования элемента, имя которого анализируется. IShellFolder::P arseDisplayName неявно проверяет существование элемента, если это поведение не переопределено специальным параметром контекста привязки.

Запросы некоторых атрибутов могут быть относительно медленными и использовать значительный объем памяти. Например, чтобы определить, является ли файл общим, оболочка загрузит сетевые компоненты. Для выполнения этой процедуры может потребоваться загрузка нескольких библиотек DLL. Назначение pdwAttributes заключается в том, чтобы разрешить ограничить запрос только той информацией, которая требуется. В следующем фрагменте кода показано, как узнать, сжимается ли файл.

LPITEMIDLIST pidl;
ULONG cbEaten;
DWORD dwAttribs = SFGAO_COMPRESSED;

hres = psf->ParseDisplayName(NULL,
                             NULL,
                             lpwszDisplayName,
                             &cbEaten,  // This can be NULL
                             &pidl,
                             &dwAttribs);

if(dwAttribs & SFGAO_COMPRESSED)
{
    // Do something with the compressed file
}

Так как pdwAttributes является параметром in/out, его всегда следует инициализировать. При передаче неинициализированного значения некоторые биты могут быть заданы непреднамеренно. Затем IShellFolder::P arseDisplayName запрашивает соответствующие атрибуты, что может привести к нежелательным задержкам или нехватке памяти. Если вы не хотите запрашивать атрибуты, задайте для pdwAttributesзначение NULL , чтобы избежать непредсказуемого поведения.

Этот метод аналогичен методу IParseDisplayName::P arseDisplayName .

Требования

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

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

IShellFolder

IShellFolder2

IShellFolder::GetAttributesOf

IShellLink