Compartilhar via

Função PropVariantChangeType (propvarutil.h)

  • Artigo

Impõe um valor armazenado como uma estrutura PROPVARIANT a um valor equivalente de um tipo variante diferente.

Sintaxe

PSSTDAPI PropVariantChangeType(
  [out] PROPVARIANT          *ppropvarDest,
  [in]  REFPROPVARIANT       propvarSrc,
  [in]  PROPVAR_CHANGE_FLAGS flags,
  [in]  VARTYPE              vt
);

Parâmetros

[out] ppropvarDest

Tipo: PROPVARIANT*

Um ponteiro para uma estrutura PROPVARIANT que, quando essa função retorna com êxito, recebe o valor coagido e seu novo tipo.

[in] propvarSrc

Tipo: REFPROPVARIANT

Uma referência à estrutura PROPVARIANT de origem que contém o valor expresso como seu tipo original.

[in] flags

Tipo: PROPVAR_CHANGE_FLAGS

Reservado, precisa ser 0.

[in] vt

Tipo: VARTYPE

Especifica o novo tipo para o valor . Consulte as tabelas abaixo para obter nomes de tipo reconhecidos.

Retornar valor

Tipo: HRESULT

Retorna S_OK se tiver êxito ou um valor de erro COM padrão, caso contrário. Se a coerção solicitada não for possível, um erro será retornado.

Comentários

Observe que as estruturas PROPVARIANT de origem e destino devem ser estruturas separadas. Não é possível substituir os dados PROPVARIANT de origem pelos novos dados de destino; tentar fazer isso resultará em um erro.

PropVariantChangeType converte valores entre os tipos a seguir da seguinte maneira. Os números referem-se às condições explicadas após as tabelas.

VT_LPWSTR VT_BSTR VT_BOOL VT_FILETIME VT_DATE VT_CLSID
VT_LPWSTR Yes Yes Sim Sim (2) Sim (2) Yes
VT_BSTR Yes Yes Sim Sim (2) Sim (2) Yes
VT_BOOL Yes Yes Yes No No No
VT_I2 Yes Yes Yes No No No
VT_I4 Yes Yes Yes No No No
VT_I8 Yes Yes Yes No No No
VT_UI2 Yes Yes Yes No No No
VT_UI4 Yes Yes Yes No No No
VT_UI8 Yes Yes Yes No No No
VT_R8 Sim (3) Sim (3) Yes No No No
VT_FILETIME Sim (2) Sim (2) No Yes Yes No
VT_DATE Sim (2) Sim (2) No Yes Yes No
VT_CLSID Yes Yes No No No Yes
 
VT_I2 VT_I4 VT_I8 VT_UI2 VT_UI4 VT_UI8 VT_R8
VT_LPWSTR Yes Yes Yes Yes Yes Yes Sim (3)
VT_BSTR Yes Yes Yes Yes Yes Yes Sim (3)
VT_BOOL Yes Yes Yes Yes Yes Yes Yes
VT_I2 Yes Yes Yes Sim (1) Sim (1) Sim (1) Sim (1)
VT_I4 Sim (1) Yes Yes Sim (1) Sim (1) Sim (1) Sim (1)
VT_I8 Sim (1) Sim (1) Yes Sim (1) Sim (1) Sim (1) Sim (1)
VT_UI2 Sim (1) Yes Yes Yes Yes Yes Sim (1)
VT_UI4 Sim (1) Sim (1) Yes Sim (1) Yes Yes Sim (1)
VT_UI8 Sim (1) Sim (1) Sim (1) Sim (1) Sim (1) Yes Sim (1)
VT_R8 Sim (1) Sim (1) Sim (1) Sim (1) Sim (1) Sim (1) Yes
VT_FILETIME No No No No No No No
VT_DATE No No No No No No No
VT_CLSID No No No No No No No
 

Condições

  1. Ao converter entre tipos numéricos, as conversões fora do intervalo falham. Por exemplo, um valor com sinal negativo para um tipo não assinado ou um valor sem sinal de 4 bytes maior que 65535 para um tipo sem sinal de 2 bytes.
  2. Ao converter entre cadeias de caracteres e datas, uma forma de cadeia de caracteres canônica é usada em vez de uma representação localizada ou "legível por humanos". O formato é "aaaa/mm/dd:hh:mm:ss.fff" (ano, mês, data, horas, minutos, segundos, milissegundos). Observe que isso é menos precisão do que é suportado pelo tipo FILETIME , mas deve ser suficiente para a maioria das finalidades.
  3. Ao converter entre números de ponto flutuante e cadeias de caracteres, o separador decimal da localidade atual é usado. Observe que isso pode causar problemas quando esses valores são salvos em arquivos movidos entre localidades diferentes.
Nota Tipos adicionais podem ter suporte no futuro.
 
Em alguns casos, há suporte para a conversão entre vetores (VT_VECTOR) e matrizes (VT_ARRAY). Quando há suporte, a contagem de elementos deve ser a mesma em cada um. Um vetor de valor único pode ser convertido em um valor não vetor, mas um vetor de vários valores não pode ser convertido em um tipo não vetor.

A coerção entre tipos é executada sem relação a informações específicas da propriedade. As coerções específicas da propriedade devem ser executadas usando PSCoerceToCanonicalValue. Além disso, se a forma de cadeia de caracteres de um valor for necessária para fins de interface do usuário, PSFormatForDisplay deverá ser usado para formatar o valor de acordo com informações específicas de localidade e propriedade, em vez de usar PropVariantChangeType para forçar o valor a uma cadeia de caracteres.

Exemplos

O exemplo de código a seguir, a ser incluído como parte de um programa maior, demonstra como usar PropVariantChangeType para inicializar um valor de VT_FILETIME de uma cadeia de caracteres.

PROPVARIANT propvarString = {0};
                    
HRESULT hr = InitPropVariantFromString(L"2007/01/30:12:00:00.000", &propvarString);
if (SUCCEEDED(hr))
{
    PROPVARIANT propvarFiletime = {0};

    hr = PropVariantChangeType(&propvarFiletime, propvarString, 0, VT_FILETIME);
    if (SUCCEEDED(hr))
    {
        // propvarFiletime now contains the FILETIME representation 
        // of 1/30/2007 12:00 PM
        PropVariantClear(&propvarFiletime);
    }
    PropVariantClear(&propvarString);
}

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP com SP2, Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 com SP1 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho propvarutil.h
Biblioteca Propsys.lib
DLL Propsys.dll (versão 6.0 ou posterior)
Redistribuível Pesquisa da Área de Trabalho do Windows (WDS) 3.0