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

Статья
11/20/2024

Функция extractIconEx создает массив дескрипторов для больших или небольших значков, извлеченных из указанного исполняемого файла, DLL или файла значков.

Синтаксис

UINT ExtractIconExA(
  [in]  LPCSTR lpszFile,
  [in]  int    nIconIndex,
  [out] HICON  *phiconLarge,
  [out] HICON  *phiconSmall,
        UINT   nIcons
);

Параметры

[in] lpszFile

Тип: LPCTSTR

Указатель на строку, завершающуюся значением NULL, которая указывает имя исполняемого файла, dll или файла значка, из которого будут извлечены значки.

[in] nIconIndex

Тип: int

Указывает отсчитываемый от нуля индекс первого значка. Например, если это значение равно нулю, функция извлекает первый значок в указанном файле.

Если это значение равно –1 и phiconLarge и phiconSmallNULL, функция возвращает общее количество значков в указанном файле. Если файл является исполняемым файлом или библиотекой DLL, возвращаемое значение — это количество RT_GROUP_ICON ресурсов. Если файл является файлом .ico, возвращаемое значение равно 1.

Если это значение является отрицательным числом и phiconLarge или phiconSmall не NULL, функция начинается с извлечения значка, идентификатор ресурса которого равен абсолютному значению nIconIndex. Например, используйте -3 для извлечения значка, идентификатор ресурса которого равен 3.

[out] phiconLarge

Тип: HICON*

Указатель на массив дескрипторов значков, получающих дескриптор больших значков, извлеченных из файла. Если этот параметр null, большие значки не извлекаются из файла.

[out] phiconSmall

Тип: HICON*

Указатель на массив дескрипторов значков, получающих дескриптор небольших значков, извлеченных из файла. Если этот параметр null, из файла извлекаются не небольшие значки.

nIcons

Тип: UINT

Количество значков, извлеченных из файла.

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

Тип: UINT

Если параметр nIconIndex -1, а параметр phiconLarge и phiconSmallNULL, то возвращаемое значение — это количество значков, содержащихся в указанном файле.

Если параметр nIconIndex имеет любое значение, отличное от -1, и phiconLarge или phiconSmall не NULL, возвращаемое значение — это количество значков, успешно извлеченных из файла.

Заметка

Если функция сталкивается с ошибкой, она возвращает UINT_MAX. В этом случае можно вызвать GetLastError, чтобы получить код ошибки. Например, эта функция возвращает UINT_MAX, если файл, указанный lpszFile не найден, пока параметр nIconIndex является любым значением, кроме -1, а phiconLarge или phiconSmall не NULL. В этом случае GetLastError возвращает ERROR_FILE_NOT_FOUND (2).

Замечания

Если они больше не нужны, необходимо уничтожить все значки, извлеченные ExtractIconEx путем вызова функции DestroyIcon.

Чтобы получить измерения больших и небольших значков, используйте эту функцию с флагами SM_CXICON, SM_CYICON, SM_CXSMICON и SM_CYSMICON.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	shellapi.h
DLL	Shell32.dll
набор API	ext-ms-win-shell-shell32-l1-2-1 (представлено в Windows 10 версии 10.0.10240)

См. также

ExtractAssociatedIcon

ExtractAssociatedIconEx

ExtractIcon

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