Método IShellItemImageFactory::GetImage (shobjidl_core.h)

Obtém um HBITMAP que representa um IShellItem. O comportamento padrão é carregar uma miniatura. Se não houver miniatura para o IShellItem atual, ele recuperará um HBITMAP para o ícone do item. A miniatura ou o ícone será extraído se não estiver armazenado em cache no momento.

Sintaxe

HRESULT GetImage(
  [in]  SIZE    size,
  [in]  SIIGBF  flags,
  [out] HBITMAP *phbm
);

Parâmetros

[in] size

Tipo: SIZE

Uma estrutura que especifica o tamanho da imagem a ser recebida.

[in] flags

Tipo: SIIGBF

Uma ou mais das seguintes opções:

SIIGBF_RESIZETOFIT (0x00000000)

Reduza o bitmap conforme necessário para se ajustar, preservando sua taxa de proporção.

SIIGBF_BIGGERSIZEOK (0x00000001)

Passados por chamadores se quiserem alongar a imagem retornada por conta própria. Por exemplo, se o chamador passar um tamanho de ícone de 80x80, uma miniatura de 96x96 poderá ser retornada. Essa ação pode ser usada como uma otimização de desempenho se o chamador espera que ele precise alongar a imagem. Observe que a implementação do Shell de IShellItemImageFactory executa um estiramento GDI blit. Se o chamador quiser um trecho de imagem de maior qualidade do que o fornecido por meio desse mecanismo, ele deverá passar esse sinalizador e executar o alongamento por conta própria.

SIIGBF_MEMORYONLY (0x00000002)

Retorne o item somente se ele já estiver na memória. Não acesse o disco mesmo se o item estiver armazenado em cache. Observe que isso só retorna um ícone já armazenado em cache e pode voltar para um ícone por classe se um item tiver um ícone por instância que não tenha sido armazenado em cache. Recuperar uma miniatura, mesmo que ela esteja armazenada em cache, sempre requer que o disco seja acessado, portanto, GetImage não deve ser chamado do thread da interface do usuário sem passar SIIGBF_MEMORYONLY.

SIIGBF_ICONONLY (0x00000004)

Retornar somente o ícone, nunca a miniatura.

SIIGBF_THUMBNAILONLY (0x00000008)

Retornar somente a miniatura, nunca o ícone. Observe que nem todos os itens têm miniaturas, portanto , SIIGBF_THUMBNAILONLY fará com que o método falhe nesses casos.

SIIGBF_INCACHEONLY (0x00000010)

Permite o acesso ao disco, mas apenas para recuperar um item armazenado em cache. Isso retornará uma miniatura armazenada em cache se ela estiver disponível. Se nenhuma miniatura armazenada em cache estiver disponível, ela retornará um ícone armazenado em cache por instância, mas não extrairá uma miniatura ou um ícone.

SIIGBF_CROPTOSQUARE (0x00000020)

Introduzido no Windows 8. Se necessário, corte o bitmap em um quadrado.

SIIGBF_WIDETHUMBNAILS (0x00000040)

Introduzido no Windows 8. Estique e corte o bitmap para uma taxa de proporção de 0,7.

SIIGBF_ICONBACKGROUND (0x00000080)

Introduzido no Windows 8. Se estiver retornando um ícone, pinte uma tela de fundo usando a cor da tela de fundo registrada do aplicativo associado.

SIIGBF_SCALEUP (0x00000100)

Introduzido no Windows 8. Se necessário, estique o bitmap para que a altura e a largura se ajustem ao tamanho especificado.

[out] phbm

Tipo: HBITMAP*

Ponteiro para um valor que, quando esse método retorna com êxito, recebe o identificador do bitmap recuperado. É responsabilidade do chamador liberar esse recurso recuperado por meio de DeleteObject quando ele não for mais necessário.

Retornar valor

Tipo: HRESULT

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

A extração de ícones pode ser demorada. Esse método geralmente não deve ser chamado de um thread de interface do usuário para evitar fazer com que esse thread fique sem resposta. Você pode chamar IShellItemImageFactory::GetImage em um thread de interface do usuário se definir o sinalizador SIIGBF_INCACHEONLY . No entanto, se a imagem não for encontrada no cache, o aplicativo de chamada deverá estar preparado para iniciar um thread em segundo plano para extrair a imagem. Uma extração nunca deve ser feita em um thread de interface do usuário.

Consulte o exemplo Usando o Image Factory para obter um exemplo completo de como usar esse método.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shobjidl_core.h (inclua Shobjidl.h)