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
S_OK	Sucesso
E_PENDING	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)