Método IExtractImage::GetLocation (shobjidl_core.h)
Obtém um caminho para a imagem que deve ser extraída.
Sintaxe
HRESULT GetLocation(
[out] LPWSTR pszPathBuffer,
[in] DWORD cch,
[out] DWORD *pdwPriority,
[in] const SIZE *prgSize,
[in] DWORD dwRecClrDepth,
[in, out] DWORD *pdwFlags
);
Parâmetros
[out] pszPathBuffer
Tipo: LPWSTR
O buffer usado para retornar a descrição do caminho. Esse valor identifica a imagem para que você possa evitar carregar a mesma mais de uma vez.
[in] cch
Tipo: DWORD
O tamanho de pszPathBuffer em caracteres.
[out] pdwPriority
Tipo: DWORD*
Não usado.
Microsoft Windows XP e versões anteriores: O ponteiro usado para retornar a prioridade do item quando o sinalizador IEIFLAG_ASYNC é definido em pdwFlags. Esse parâmetro não deve ser NULL. A função falhará se esse parâmetro for NULL, se IEIFLAG_ASYNC sinalizador estiver definido ou não.
Esse parâmetro normalmente é usado para indicar a quantidade de tempo necessária para extrair a imagem. Se você quiser mais controle sobre a ordem em que as miniaturas são extraídas, poderá definir vários níveis de prioridade, até 32 bits. Desde que os valores inteiros atribuídos aos diferentes níveis de prioridade aumentem de baixa para alta prioridade, os números reais usados não são importantes. Elas são usadas apenas para determinar a ordem na qual as imagens serão extraídas. Há três níveis de prioridade padrão:
IEI_PRIORITY_MAX
Prioridade máxima.
IEI_PRIORITY_MIN
Prioridade mínima.
IEIT_PRIORITY_NORMAL
Prioridade normal.
Microsoft Windows XP. Não usado.
[in] prgSize
Tipo: const SIZE*
Um ponteiro para uma estrutura SIZE com a largura e a altura desejadas da imagem. Não deve ser NULL.
[in] dwRecClrDepth
Tipo: DWORD
A profundidade de cor recomendada em unidades de bits por pixel. Não deve ser NULL.
[in, out] pdwFlags
Tipo: DWORD*
Sinalizadores que especificam como a imagem deve ser tratada. O valor deve ser um ou mais dos seguintes:
IEIFLAG_ASPECT
Usado para solicitar que o objeto use a taxa de proporção fornecida. Se esse sinalizador for definido, um retângulo com a taxa de proporção desejada será passado em prgSize. Esse sinalizador não pode ser usado com IEIFLAG_SCREEN.
IEIFLAG_ASYNC
Não usado. A miniatura é sempre extraída em um thread em segundo plano.
Microsoft Windows XP e versões anteriores. Usado para perguntar se essa instância dá suporte à extração assíncrona (sem thread). Se esse sinalizador for definido pelos aplicativos de chamada, IExtractImage::GetLocation poderá retornar E_PENDING, indicando ao aplicativo de chamada para extrair a imagem em outro thread. Se E_PENDING for retornado, a prioridade do item será retornada em pdwPriority.
IEIFLAG_CACHE
Sem suporte.
Windows XP e anteriores: Definido pelo objeto para indicar que ele não armazenará a imagem em cache. Se esse sinalizador for retornado, o Shell armazenará em cache uma cópia da imagem.
IEIFLAG_GLEAM
Sem suporte.
IEIFLAG_NOBORDER (0x0100)
Sem suporte.
IEIFLAG_NOSTAMP (0x0080)
Sem suporte.
IEIFLAG_OFFLINE
Usado para instruir o objeto a usar apenas o conteúdo local para renderização.
IEIFLAG_ORIGSIZE
Versão 5.0. Usado para dizer ao objeto para renderizar a imagem para o tamanho aproximado passado em prgSize, mas recortá-la, se necessário.
IEIFLAG_QUALITY (0x0200)
Passado para o método IExtractImage::Extract para indicar que uma imagem de maior qualidade é solicitada.
Se esse sinalizador não estiver definido, IExtractImage recuperará uma miniatura inserida se o arquivo tiver uma, independentemente do tamanho solicitado pelo usuário. Por exemplo, se o arquivo for 2000x2000 pixels, mas a miniatura inserida for de apenas 100 x 100 pixels e o usuário não definir esse sinalizador, mas solicitar uma miniatura de 1000x1000 pixels, IExtractImage sempre retornará a miniatura de 100x100 pixels. Isso ocorre por design, já que IExtractImage não é escalado verticalmente. Se uma miniatura maior for desejada (geralmente as miniaturas inseridas são 160x160), esse sinalizador deve ser definido.
IEIFLAG_REFRESH (0x0400)
Retornado pelo objeto para indicar que Atualizar Miniatura deve ser exibido no menu de atalho do item.
IEIFLAG_SCREEN
Usado para instruir o objeto a renderizar como se fosse para a tela. Esse sinalizador não pode ser usado com IEIFLAG_ASPECT.
Valor retornado
Tipo: HRESULT
Esse método pode retornar um código de erro definido por COM ou um dos seguintes:
| Código de retorno | Descrição |
|---|---|
|
Sucesso |
|
Windows XP e anteriores: Se o sinalizador IEIFLAG_ASYNC estiver definido, esse valor retornado será usado para indicar ao Shell que o objeto é de thread livre. |
Comentários
Microsoft Windows XP e versões anteriores: Esse método retorna o caminho para uma imagem e especifica como a imagem deve ser renderizada. IExtractImage::GetLocation é de thread livre, ou seja, dá suporte ao MTA (Multithreaded Apartment Model), portanto, ele pode ser colocado em um thread em segundo plano. O objeto também deve expor uma interface IRunnableTask , para que o aplicativo de chamada possa iniciar e interromper o processo de extração conforme necessário.
Você deve retornar imagens que se ajustem dentro dos limites definidos por prgSize. Com o Windows 2000 e sistemas posteriores, você pode definir IEIFLAG_ORIGSIZE para usar objetos que não têm uma taxa de proporção padrão e eles serão exibidos corretamente. Você não precisa preencher a parte não utilizado do retângulo. Se você tentar usar uma imagem de taxa de proporção não padrão com versões anteriores do Shell, ela será ampliada para se ajustar ao retângulo prgSize . Dependendo do quanto a taxa de proporção difere da especificada, a imagem pode estar muito distorcida.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | shobjidl_core.h (inclua Shobjidl.h) |
| DLL | Shell32.dll (versão 4.70 ou posterior) |