Метод IExtractIconA::GetIconLocation (shlobj_core.h)

Статья
03/15/2023

Возвращает расположение и индекс значка.

Синтаксис

HRESULT GetIconLocation(
        UINT uFlags,
  [out] PSTR pszIconFile,
        UINT cchMax,
  [out] int  *piIndex,
  [out] UINT *pwFlags
);

Параметры

uFlags

Тип: UINT

Одно или несколько из следующих значений. Этот параметр также может иметь значение NULL.

GIL_ASYNC (0x0020)

Установите этот флаг, чтобы определить, следует ли извлекать значок асинхронно. Если значок можно быстро извлечь, этот флаг обычно игнорируется. Если извлечение займет больше времени, GetIconLocation должен вернуть E_PENDING. Дополнительные сведения см. в разделе Примечания.

GIL_DEFAULTICON (0x0040)

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

GIL_FORSHELL (0x0002)

Значок отображается в папке оболочки.

GIL_FORSHORTCUT (0x0080)

Значок обозначает ярлык. Однако средство извлечения значков не должно применять наложение ярлыков; это будет сделано позже. Значки ярлыков не зависят от состояния.

GIL_OPENICON (0x0001)

Значок находится в открытом состоянии, если доступны изображения с открытым и закрытым состоянием. Если этот флаг не указан, значок находится в обычном или закрытом состоянии. Этот флаг обычно используется для объектов folder.

GIL_CHECKSHIELD (0x0200)

Явным образом возвращается GIL_SHIELD или GIL_FORCENOSHIELD в pwFlags. Не блокируйте, если задано GIL_ASYNC.

[out] pszIconFile

Тип: PTSTR

Указатель на буфер, получающий расположение значка. Расположение значка — это строка, заканчивающаяся null, которая идентифицирует файл, содержащий значок.

cchMax

Тип: UINT

Размер буфера в символах, на который указывает pszIconFile.

[out] piIndex

Тип: int*

Указатель на int , получающий индекс значка в файле, на который указывает pszIconFile.

[out] pwFlags

Тип: UINT*

Указатель на значение UINT , которое получает ноль или сочетание следующих значений.

GIL_DONTCACHE (0x0010)

Биты физического изображения для этого значка не кэшируются вызывающим приложением.

GIL_NOTFILENAME (0x0008)

Расположение не является парой имени файла и индекса. Значения в pszIconFile и piIndex нельзя передать в ExtractIcon или ExtractIconEx.

Если этот флаг опущен, значение, возвращаемое в pszIconFile , представляет собой полное имя пути к .ico файлу или файлу, который может содержать значки. Кроме того, значение, возвращаемое в piIndex , является индексом в этом файле, который определяет, какой из его значков использовать. Таким образом, если флаг GIL_NOTFILENAME опущен, эти значения можно передать в ExtractIcon или ExtractIconEx.

GIL_PERCLASS (0x0004)

Все объекты этого класса имеют один и тот же значок. Этот флаг используется внутри оболочки. Типичные реализации IExtractIcon не требуют этого флага, так как флаг подразумевает, что обработчик значков не требуется для разрешения значка для каждого объекта. Рекомендуемый метод реализации значков для каждого класса — регистрация DefaultIcon для класса .

GIL_PERINSTANCE (0x0002)

Каждый объект этого класса имеет свой собственный значок. Этот флаг используется оболочкой для обработки таких случаев, как Setup.exe, где объекты с одинаковыми именами могут иметь разные значки. Типичные реализации IExtractIcon не требуют этого флага.

GIL_SIMULATEDOC (0x0001)

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

GIL_SHIELD (0x0200)

Только Windows Vista. Вызывающее приложение должно пометить значок щитом UAC.

GIL_FORCENOSHIELD (0x0400)

Только Windows Vista. Вызывающее приложение не должно помечать значок щитом UAC.

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

Тип: HRESULT

Возвращает S_OK, если функция вернула допустимое расположение, или S_FALSE, если в оболочке должен использоваться значок по умолчанию. Если флаг GIL_ASYNC задан в uFlags, метод может вернуть E_PENDING, чтобы указать, что извлечение значков займет много времени.

Когда клиент устанавливает флаг GIL_ASYNC в uFlags и получает E_PENDING в качестве возвращаемого значения, обычно создается фоновый поток для извлечения значка. Он вызывает GetIconLocation из этого потока без флага GIL_ASYNC , чтобы получить расположение значка. Затем он вызывает IExtractIcon::Extract для извлечения значка. Возврат E_PENDING означает, что объект является свободным потоком. Другими словами, его можно безопасно вызывать одновременно несколькими потоками.

Флаг GIL_DEFAULTICON обычно устанавливается в том случае, если нужный значок найден, но этот значок отсутствует в кэше значков. Извлечение значков — это фоновый процесс с низким приоритетом, который может быть отложен другими процессами. Значок по умолчанию будет отображаться вместо окончательного значка в течение времени, необходимого для извлечения, добавления в кэш и его доступности.

Требования

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

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