Função ExtractAssociatedIconA (shellapi.h)

Artigo
11/20/2024

Obtém um identificador para um ícone armazenado como um recurso em um arquivo ou um ícone armazenado no arquivo executável associado de um arquivo.

Sintaxe

HICON ExtractAssociatedIconA(
  [in]      HINSTANCE hInst,
  [in, out] LPSTR     pszIconPath,
  [in, out] WORD      *piIcon
);

Parâmetros

[in] hInst

Tipo: HINSTANCE

Um identificador para a instância do aplicativo de chamada.

[in, out] pszIconPath

Tipo: LPTSTR

Ponteiro para uma cadeia de caracteres que, na entrada, especifica o caminho completo e o nome do arquivo que contém o ícone. A função extrai o identificador de ícone desse arquivo ou de um arquivo executável associado a esse arquivo.

Quando essa função retorna, se o identificador de ícone foi obtido de um arquivo executável (um arquivo executável apontado por lpIconPath ou um arquivo executável associado), a função armazena o caminho completo e o nome do arquivo desse executável no buffer apontado por esse parâmetro.

[in, out] piIcon

Tipo: LPWORD

Ponteiro para um valor WORD que, na entrada, especifica o índice do ícone cujo identificador deve ser obtido.

Quando a função retorna, se o identificador de ícone foi obtido de um arquivo executável (um arquivo executável apontado por lpIconPath ou um arquivo executável associado), esse valor aponta para o índice do ícone nesse arquivo.

Valor de retorno

Tipo: HICON

Se a função for bem-sucedida, o valor retornado será um identificador de ícone. Se o ícone for extraído de um arquivo executável associado, a função armazenará o caminho completo e o nome do arquivo executável na cadeia de caracteres apontada por lpIconPath e armazenará o identificador do ícone no word apontado por lpiIcon.

Se a função falhar, o valor retornado será NULL.

Observações

Quando não for mais necessário, o chamador será responsável por liberar o identificador de ícone retornado por ExtractAssociatedIcon chamando a função DestroyIcon.

A função ExtractAssociatedIcon procura primeiro o ícone indexado no arquivo especificado por lpIconPath. Se a função não puder obter o identificador de ícone desse arquivo e o arquivo tiver um arquivo executável associado, ele procurará nesse arquivo executável um ícone. As associações com arquivos executáveis são baseadas em extensões de nome de arquivo e são armazenadas na parte por usuário do registro.

Nota

O cabeçalho shellapi.h define ExtractAssociatedIcon 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

ExtractAssociatedIconEx

ExtractIcon

ExtractIconEx

Compartilhar via