Функция SHGetFileInfoA (shellapi.h)

Статья
11/20/2024

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

Синтаксис

DWORD_PTR SHGetFileInfoA(
  [in]      LPCSTR      pszPath,
            DWORD       dwFileAttributes,
  [in, out] SHFILEINFOA *psfi,
            UINT        cbFileInfo,
            UINT        uFlags
);

Параметры

[in] pszPath

Тип: LPCTSTR

Указатель на строку null- завершенную строку максимальной длины MAX_PATH, содержащую имя пути и файла. Допустимы абсолютные и относительные пути.

Если параметр uFlags включает флаг SHGFI_PIDL, этот параметр должен быть адресом структуры ITEMIDLIST (PIDL), содержащей список идентификаторов элементов, которые однозначно идентифицируют файл в пространстве имен Оболочки. PIDL должен быть полным идентификатором PIDL. Относительные ПИН-адреса не допускаются.

Если параметр uFlags включает флаг SHGFI_USEFILEATTRIBUTES, этот параметр не должен быть допустимым именем файла. Функция будет продолжаться, как если файл существует с указанным именем и атрибутами файла, переданными в параметре dwFileAttributes. Это позволяет получить сведения о типе файла, передав только расширение для pszPath и передав FILE_ATTRIBUTE_NORMAL в dwFileAttributes.

Эта строка может использовать короткие (формы 8.3) или длинные имена файлов.

dwFileAttributes

Тип: DWORD

Сочетание одного или нескольких флагов атрибутов файлов (FILE_ATTRIBUTE_ значений, как определено в Winnt.h). Если uFlags не включает флаг SHGFI_USEFILEATTRIBUTES, этот параметр игнорируется.

[in, out] psfi

Тип: SHFILEINFO*

Указатель на структуру SHFILEINFO для получения сведений о файле.

cbFileInfo

Тип: UINT

Размер в байтах структуры SHFILEINFO , на которую указывает параметр psfi.

uFlags

Тип: UINT

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

SHGFI_ADDOVERLAYS (0x000000020)

версии 5.0. Примените соответствующие наложения к значку файла. Также необходимо задать флаг SHGFI_ICON.

SHGFI_ATTR_SPECIFIED (0x000020000)

Измените SHGFI_ATTRIBUTES, чтобы указать, что dwAttributes член структуры SHFILEINFO в psfi содержит необходимые атрибуты. Эти атрибуты передаются в IShellFolder::GetAttributesOf. Если этот флаг не указан, 0xFFFFFFFF передается IShellFolder::GetAttributesOf, запрашивая все атрибуты. Этот флаг нельзя указать с помощью флага SHGFI_ICON.

SHGFI_ATTRIBUTES (0x000000800)

Получение атрибутов элемента. Атрибуты копируются в элемент dwAttributes структуры, указанной в параметре psfi. Это те же атрибуты, которые получены из IShellFolder::GetAttributesOf.

SHGFI_DISPLAYNAME (0x000000200)

Получите отображаемое имя файла, имя которого отображается в проводнике Windows. Имя копируется в элемент szDisplayName структуры, указанной в psfi. Возвращаемое отображаемое имя использует длинное имя файла, а не форму 8.3 имени файла. Обратите внимание, что отображаемое имя может повлиять на такие параметры, как отображение расширений.

SHGFI_EXETYPE (0x000002000)

Получите тип исполняемого файла, если pszPath идентифицирует исполняемый файл. Сведения упакованы в возвращаемое значение. Этот флаг нельзя указать с другими флагами.

SHGFI_ICON (0x000000100)

Извлеките дескриптор на значок, представляющий файл и индекс значка в списке системных образов. Дескриптор копируется в элемент hIcon структуры, указанной psfi, и индекс копируется в элемент iIcon.

SHGFI_ICONLOCATION (0x000001000)

Получите имя файла, содержащего значок, представляющий файл, указанный pszPath, как возвращается методом IExtractIcon::GetIconLocation обработчика значков файла. Также извлеките индекс значка в этом файле. Имя файла, содержащего значок, копируется в элемент szDisplayName структуры, указанной psfi. Индекс значка копируется в элемент iIcon структуры.

SHGFI_LARGEICON (0x000000000)

Измените SHGFI_ICON, что приводит к получению большого значка файла. Также необходимо задать флаг SHGFI_ICON.

SHGFI_LINKOVERLAY (0x000008000)

Измените SHGFI_ICON, в результате чего функция добавит наложение ссылки на значок файла. Также необходимо задать флаг SHGFI_ICON.

SHGFI_OPENICON (0x000000002)

Измените SHGFI_ICON, что приводит к получению значка открытия файла. Также используется для изменения SHGFI_SYSICONINDEX, в результате чего функция возвращает дескриптор в список системных образов, содержащий небольшой значок открытия файла. Объект контейнера отображает открытый значок, указывающий, что контейнер открыт. Также необходимо задать флаг SHGFI_ICON или SHGFI_SYSICONINDEX.

SHGFI_OVERLAYINDEX (0x000000040)

версии 5.0. Возвращает индекс значка наложения. Значение индекса наложения возвращается в верхних восьми битах элемента iIcon структуры, указанной psfi. Для этого флага также требуется задать SHGFI_ICON.

SHGFI_PIDL (0x000000008)

Укажите, что pszPath — это адрес структуры itemIDLIST , а не имени пути.

SHGFI_SELECTED (0x000010000)

Измените SHGFI_ICON, что приводит к смешении значка файла с цветом выделения системы. Также необходимо задать флаг SHGFI_ICON.

SHGFI_SHELLICONSIZE (0x000000004)

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

SHGFI_SMALLICON (0x000000001)

Измените SHGFI_ICON, что приводит к получению маленького значка файла. Также используется для изменения SHGFI_SYSICONINDEX, в результате чего функция возвращает дескриптор в список системных образов, содержащий небольшие изображения значков. Также необходимо задать флаг SHGFI_ICON или SHGFI_SYSICONINDEX.

SHGFI_SYSICONINDEX (0x000004000)

Получение индекса значка списка системных образов. В случае успешного выполнения индекс копируется в элемент iIconpsfi. Возвращаемое значение — это дескриптор списка системных образов. Допустимы только те изображения, индексы которых успешно копируются в iIcon. Попытка получить доступ к другим изображениям в списке системных образов приведет к неопределенному поведению.

SHGFI_TYPENAME (0x000000400)

Получите строку, описывающую тип файла. Строка копируется в элемент szTypeName структуры, указанной в psfi.

SHGFI_USEFILEATTRIBUTES (0x000000010)

Указывает, что функция не должна пытаться получить доступ к файлу, указанному pszPath. Скорее, он должен действовать так, как если бы файл, указанный pszPath существует с атрибутами файла, переданными в dwFileAttributes. Этот флаг нельзя объединить с флагами SHGFI_ATTRIBUTES, SHGFI_EXETYPEили флагами SHGFI_PIDL.

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

Тип: DWORD_PTR

Возвращает значение, значение которого зависит от параметра uFlags.

Если uFlags не содержит SHGFI_EXETYPE или SHGFI_SYSICONINDEX, возвращаемое значение ненулевое, если выполнено успешно, или ноль в противном случае.

Если uFlags содержит флаг SHGFI_EXETYPE, возвращаемое значение указывает тип исполняемого файла. Это будет одно из следующих значений.

Возвращаемый код	Описание
0	Неисключаемый файл или условие ошибки.
LOWORD = NE или PE и HIWORD = версия Windows	Приложение Windows.
LOWORD = MZ и HIWORD = 0	MS-DOS .exe или файл .com
LOWORD = PE и HIWORD = 0	Консольное приложение или файл .bat

Замечания

Эту функцию следует вызвать из фонового потока. Сбой этого может привести к остановке реагирования пользовательского интерфейса.

Если SHGetFileInfo возвращает дескриптор значка в элементе hIcon структуры SHFILEINFO, на которую указывает psfi, вы несете ответственность за освобождение его с помощью DestroyIcon, если он больше не нужен.

Примечание После того, как у вас есть дескриптор списка системных образов, вы можете использовать API списка изображений для управления им, как и с любым другим списком изображений. Так как системные списки образов создаются на основе каждого процесса, их следует рассматривать как объекты только для чтения. Запись в список системных образов может перезаписать или удалить один из системных образов, что делает его недоступным или неправильным для остальной части процесса.

Перед вызовом SHGetFileInfoнеобходимо инициализировать объектную модель компонента (COM ) или OleInitialize.

При использовании флага SHGFI_EXETYPE с приложением Windows версия исполняемого файла Windows будет указана в HIWORD возвращаемого значения. Эта версия возвращается в виде шестнадцатеричного значения. Дополнительные сведения о том, как приравнять это значение с определенной версией Windows, см. использование заголовков Windows.

Примеры

В следующем примере кода используется SHGetFileInfo для получения отображаемого имени корзины, определяемого его PIDL.

LPITEMIDLIST pidl = NULL;
hr = SHGetFolderLocation(NULL, CSIDL_BITBUCKET, NULL, 0, &pidl);

if (SUCCEEDED(hr))                    
{
    SHFILEINFOW sfi = {0};
    hr = SHGetFileInfo((LPCTSTR)pidl,
                        -1,
                        &sfi,
                        sizeof(sfi),
                        SHGFI_PIDL | SHGFI_DISPLAYNAME)
            
    if (SUCCEEDED(hr))
    {
        // The display name is now held in sfi.szDisplayName.
    }
}

ILFree(pidl);

Заметка

Заголовок shellapi.h определяет SHGetFileInfo как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	shellapi.h
библиотеки	Shell32.lib
DLL	Shell32.dll (версия 4.0 или более поздняя версия)

См. также

FileIconInit

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