Função ExtractIconExA (shellapi.h)

Artigo
11/20/2024

A função ExtractIconEx cria uma matriz de identificadores para ícones grandes ou pequenos extraídos do arquivo executável, DLL ou 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 estiverem 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 de retorno

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 estiver NULL, o valor retornado será o número de ícones extraídos com êxito do arquivo.

Nota

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).

Observações

Quando eles não forem mais necessários, você deve 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shellapi.h
de DLL	Shell32.dll
conjunto de API	ext-ms-win-shell-shell32-l1-2-1 (introduzido no Windows 10, versão 10.0.10240)

Consulte também

ExtractAssociatedIcon

ExtractAssociatedIconEx

ExtractIcon

Compartilhar via