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

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

  • Статья

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

Синтаксис

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
 ФАЙЛ .exe или .com MS-DOS
LOWORD = PE и HIWORD = 0
 Консольное приложение или файл .bat

Комментарии

Эту функцию следует вызывать из фонового потока. В противном случае пользовательский интерфейс перестанет отвечать на запросы.

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

Примечание Получив дескриптор списка системных образов, вы можете использовать API списка образов для управления им, как и с любым другим списком изображений. Так как списки образов системы создаются для каждого процесса, их следует рассматривать как объекты, доступные только для чтения. Запись в список системных образов может перезаписать или удалить один из образов системы, что делает его недоступным или неправильным для оставшейся части процесса.
 
Перед вызовом SHGetFileInfo необходимо инициализировать компонентную объектную модель (COM) с помощью CoInitialize или 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 [только классические приложения]
Целевая платформа Windows
Header shellapi.h
Библиотека Shell32.lib
DLL Shell32.dll (версия 4.0 или более поздняя)

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

FileIconInit