Função ExtractIconExA (shellapi.h)

A função ExtractIconEx cria uma matriz de identificadores para ícones grandes ou pequenos extraídos do arquivo executável, da DLL ou do arquivo de ícone especificado.

Sintaxe

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

Parâmetros

[in] lpszFile

Tipo: LPCTSTR

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome de um arquivo executável, DLL ou arquivo de ícone do qual os ícones serão extraídos.

[in] nIconIndex

Tipo: int

Especifica o índice baseado em zero do primeiro ícone a ser extraído. Por exemplo, se esse valor for zero, a função extrairá o primeiro ícone no arquivo especificado.

Se esse valor for –1 e phiconLarge e phiconSmall forem NULL, a função retornará o número total de ícones no arquivo especificado. Se o arquivo for um arquivo executável ou DLL, o valor retornado será o número de recursos RT_GROUP_ICON. Se o arquivo for um arquivo .ico, o valor retornado será 1.

Se esse valor for um número negativo e phiconLarge ou phiconSmall não for NULL, a função começará extraindo o ícone cujo identificador de recurso é igual ao valor absoluto de nIconIndex. Por exemplo, use -3 para extrair o ícone cujo identificador de recurso é 3.

[out] phiconLarge

Tipo: HICON*

Ponteiro para uma matriz de identificadores de ícone que recebe identificadores para os ícones grandes extraídos do arquivo. Se esse parâmetro for NULL, nenhum ícone grande será extraído do arquivo.

[out] phiconSmall

Tipo: HICON*

Ponteiro para uma matriz de identificadores de ícone que recebe identificadores para os ícones pequenos extraídos do arquivo. Se esse parâmetro for NULL, nenhum ícone pequeno será extraído do arquivo.

nIcons

Tipo: UINT

O número de ícones a serem extraídos do arquivo.

Valor retornado

Tipo: UINT

Se o parâmetro nIconIndex for -1 e os parâmetros phiconLarge e phiconSmall forem NULL, o valor retornado será o número de ícones contidos no arquivo especificado.

Se o parâmetro nIconIndex for qualquer valor diferente de -1 e phiconLarge ou phiconSmall não for NULL, o valor retornado será o número de ícones extraídos com êxito do arquivo.

Observação

Se a função encontrar um erro, ela retornará UINT_MAX. Nesse caso, você pode chamar GetLastError para recuperar o código de erro. Por exemplo, essa função retornará UINT_MAX se o arquivo especificado por lpszFile não puder ser encontrado enquanto o parâmetro nIconIndex for qualquer valor diferente de -1 e phiconLarge ou phiconSmall não for NULL. Nesse caso, GetLastError retorna ERROR_FILE_NOT_FOUND (2).

Comentários

Quando eles não forem mais necessários, você deverá destruir todos os ícones extraídos por ExtractIconEx chamando a função DestroyIcon .

Para recuperar as dimensões dos ícones grandes e pequenos, use essa função com os sinalizadores SM_CXICON, SM_CYICON, SM_CXSMICON e SM_CYSMICON.

Observação

O cabeçalho shellapi.h define ExtractIconEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shellapi.h
DLL	Shell32.dll
Conjunto de APIs	ext-ms-win-shell32-l1-2-1 (introduzido no Windows 10, versão 10.0.10240)

Confira também

ExtractAssociatedIcon

ExtractAssociatedIconEx

ExtractIcon