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