Método IExtractIconA::GetIconLocation (shlobj_core.h)

Obtém o local e o índice de um ícone.

Sintaxe

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

Parâmetros

uFlags

Tipo: UINT

Um ou mais dos valores a seguir. Esse parâmetro também pode ser NULL.

GIL_ASYNC (0x0020)

Defina esse sinalizador para determinar se o ícone deve ser extraído de forma assíncrona. Se o ícone puder ser extraído rapidamente, esse sinalizador geralmente será ignorado. Se a extração levar mais tempo, GetIconLocation deverá retornar E_PENDING. Consulte os Comentários para mais discussões.

GIL_DEFAULTICON (0x0040)

Recupere informações sobre o ícone de fallback. Os ícones de fallback geralmente são usados enquanto o ícone desejado é extraído e adicionado ao cache.

GIL_FORSHELL (0x0002)

O ícone é exibido em uma pasta Shell.

GIL_FORSHORTCUT (0x0080)

O ícone indica um atalho. No entanto, o extrator de ícone não deve aplicar a sobreposição de atalho; que será feito mais tarde. Os ícones de atalho são independentes de estado.

GIL_OPENICON (0x0001)

O ícone estará no estado aberto se as imagens de estado aberto e de estado fechado estiverem disponíveis. Se esse sinalizador não for especificado, o ícone estará no estado normal ou fechado. Esse sinalizador normalmente é usado para objetos de pasta.

GIL_CHECKSHIELD (0x0200)

Retornar explicitamente GIL_SHIELD ou GIL_FORCENOSHIELD em pwFlags. Não bloqueie se GIL_ASYNC estiver definido.

[out] pszIconFile

Tipo: PTSTR

Um ponteiro para um buffer que recebe o local do ícone. O local do ícone é uma cadeia de caracteres terminada em nulo que identifica o arquivo que contém o ícone.

cchMax

Tipo: UINT

O tamanho do buffer, em caracteres, apontado por pszIconFile.

[out] piIndex

Tipo: int*

Um ponteiro para um int que recebe o índice do ícone no arquivo apontado por pszIconFile.

[out] pwFlags

Tipo: UINT*

Um ponteiro para um valor UINT que recebe zero ou uma combinação dos valores a seguir.

GIL_DONTCACHE (0x0010)

Os bits de imagem física para esse ícone não são armazenados em cache pelo aplicativo de chamada.

GIL_NOTFILENAME (0x0008)

O local não é um par nome de arquivo/índice. Os valores em pszIconFile e piIndex não podem ser passados para ExtractIcon ou ExtractIconEx.

Quando esse sinalizador é omitido, o valor retornado em pszIconFile é um nome de caminho totalmente qualificado para um arquivo .ico ou para um arquivo que pode conter ícones. Além disso, o valor retornado em piIndex é um índice nesse arquivo que identifica qual de seus ícones usar. Portanto, quando o sinalizador GIL_NOTFILENAME é omitido, esses valores podem ser passados para ExtractIcon ou ExtractIconEx.

GIL_PERCLASS (0x0004)

Todos os objetos dessa classe têm o mesmo ícone. Esse sinalizador é usado internamente pelo Shell. Implementações típicas de IExtractIcon não exigem esse sinalizador porque o sinalizador implica que um manipulador de ícones não é necessário para resolve o ícone por objeto. O método recomendado para implementar ícones por classe é registrar um DefaultIcon para a classe .

GIL_PERINSTANCE (0x0002)

Cada objeto dessa classe tem seu próprio ícone. Esse sinalizador é usado internamente pelo Shell para lidar com casos como Setup.exe, em que objetos com nomes idênticos podem ter ícones diferentes. Implementações típicas de IExtractIcon não exigem esse sinalizador.

GIL_SIMULATEDOC (0x0001)

O aplicativo de chamada deve criar um ícone de documento usando o ícone especificado.

GIL_SHIELD (0x0200)

Somente Windows Vista. O aplicativo de chamada deve carimbar o ícone com o escudo UAC.

GIL_FORCENOSHIELD (0x0400)

Somente Windows Vista. O aplicativo de chamada não deve carimbar o ícone com o escudo UAC.

Retornar valor

Tipo: HRESULT

Retorna S_OK se a função retornou um local válido ou S_FALSE se o Shell deve usar um ícone padrão. Se o sinalizador GIL_ASYNC for definido em uFlags, o método poderá retornar E_PENDING para indicar que a extração de ícones será demorada.

Comentários

Quando um cliente define o sinalizador GIL_ASYNC em uFlags e recebe E_PENDING como um valor retornado, ele normalmente cria um thread em segundo plano para extrair o ícone. Ele chama GetIconLocation desse thread, sem o sinalizador GIL_ASYNC , para recuperar o local do ícone. Em seguida, ele chama IExtractIcon::Extract para extrair o ícone. Retornar E_PENDING implica que o objeto é threaded livre. Em outras palavras, ele pode ser chamado simultaneamente por vários threads.

O sinalizador GIL_DEFAULTICON geralmente é definido no caso em que o ícone desejado é encontrado, mas esse ícone não está presente no cache de ícones. A extração de ícones é um processo em segundo plano de baixa prioridade e, como tal, pode ser atrasada por outros processos. O ícone padrão será exibido no lugar do ícone final durante o tempo necessário para que esse ícone final seja extraído, adicionado ao cache e disponibilizado.

Requisitos

Requisito	Valor
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	shlobj_core.h
DLL	Shell32.dll (versão 4.0 ou posterior)