Función PropVariantChangeType (propvarutil.h)

Convierte un valor almacenado como una estructura PROPVARIANT en un valor equivalente de un tipo de variante diferente.

Sintaxis

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

Parámetros

[out] ppropvarDest

Tipo: PROPVARIANT*

Puntero a una estructura PROPVARIANT que, cuando esta función devuelve correctamente, recibe el valor coerced y su nuevo tipo.

[in] propvarSrc

Tipo: REFPROPVARIANT

Referencia a la estructura PROPVARIANT de origen que contiene el valor expresado como su tipo original.

[in] flags

Tipo: PROPVAR_CHANGE_FLAGS

Reservado, debe ser 0.

[in] vt

Tipo: VARTYPE

Especifica el nuevo tipo para el valor. Consulte las tablas siguientes para ver los nombres de tipo reconocidos.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se ejecuta correctamente o un valor de error COM estándar de lo contrario. Si la coerción solicitada no es posible, se devuelve un error.

Comentarios

Tenga en cuenta que las estructuras PROPVARIANT de origen y destino deben ser estructuras independientes. No se pueden sobrescribir los datos PROPVARIANT de origen con los nuevos datos de destino; si intenta hacerlo, se producirá un error.

PropVariantChangeType convierte los valores entre los siguientes tipos como se indica a continuación. Los números hacen referencia a las condiciones que se explican después de las tablas.

	VT_LPWSTR	VT_BSTR	VT_BOOL	VT_FILETIME	VT_DATE	VT_CLSID
VT_LPWSTR	Sí	Sí	Sí	Sí (2)	Sí (2)	Sí
VT_BSTR	Sí	Sí	Sí	Sí (2)	Sí (2)	Sí
VT_BOOL	Sí	Sí	Sí	No	No	No
VT_I2	Sí	Sí	Sí	No	No	No
VT_I4	Sí	Sí	Sí	No	No	No
VT_I8	Sí	Sí	Sí	No	No	No
VT_UI2	Sí	Sí	Sí	No	No	No
VT_UI4	Sí	Sí	Sí	No	No	No
VT_UI8	Sí	Sí	Sí	No	No	No
VT_R8	Sí (3)	Sí (3)	Sí	No	No	No
VT_FILETIME	Sí (2)	Sí (2)	No	Sí	Sí	No
VT_DATE	Sí (2)	Sí (2)	No	Sí	Sí	No
VT_CLSID	Sí	Sí	No	No	No	Sí

 

	VT_I2	VT_I4	VT_I8	VT_UI2	VT_UI4	VT_UI8	VT_R8
VT_LPWSTR	Sí	Sí	Sí	Sí	Sí	Sí	Sí (3)
VT_BSTR	Sí	Sí	Sí	Sí	Sí	Sí	Sí (3)
VT_BOOL	Sí	Sí	Sí	Sí	Sí	Sí	Sí
VT_I2	Sí	Sí	Sí	Sí (1)	Sí (1)	Sí (1)	Sí (1)
VT_I4	Sí (1)	Sí	Sí	Sí (1)	Sí (1)	Sí (1)	Sí (1)
VT_I8	Sí (1)	Sí (1)	Sí	Sí (1)	Sí (1)	Sí (1)	Sí (1)
VT_UI2	Sí (1)	Sí	Sí	Sí	Sí	Sí	Sí (1)
VT_UI4	Sí (1)	Sí (1)	Sí	Sí (1)	Sí	Sí	Sí (1)
VT_UI8	Sí (1)	Sí (1)	Sí (1)	Sí (1)	Sí (1)	Sí	Sí (1)
VT_R8	Sí (1)	Sí (1)	Sí (1)	Sí (1)	Sí (1)	Sí (1)	Sí
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

 

Condiciones

1. Al convertir entre tipos numéricos, se produce un error en las conversiones fuera del intervalo. Por ejemplo, un valor con signo negativo en un tipo sin signo o un valor sin signo de 4 bytes mayor que 65535 a un tipo sin signo de 2 bytes.
2. Al convertir entre cadenas y fechas, se usa un formulario de cadena canónica en lugar de una representación localizada o "legible". El formato es "aaaa/mm/dd:hh:mm:ss.fff" (año, mes, fecha, horas, minutos, segundos, milisegundos). Tenga en cuenta que esta es menos precisión de la que admite el tipo FILETIME , pero debe ser suficiente para la mayoría de los propósitos.
3. Al convertir entre números de punto flotante y cadenas, se usa el separador decimal de la configuración regional actual. Tenga en cuenta que esto puede causar problemas cuando estos valores se guardan en archivos que se mueven entre diferentes configuraciones regionales.

Nota Es posible que se admita más tipos en el futuro.

 

La conversión entre vectores (VT_VECTOR) y matrices (VT_ARRAY) se admite en algunos casos. Cuando se admite, el recuento de elementos debe ser el mismo en cada uno de ellos. Un vector con un solo valor se puede convertir en un valor no vectorial, pero no se puede convertir un vector multivalor en un tipo no vectorial.

La coerción entre tipos se realiza sin tener en cuenta la información específica de la propiedad. Las coerciones específicas de la propiedad se deben realizar mediante PSCoerceToCanonicalValue. Además, si se necesita la forma de cadena de un valor con fines de interfaz de usuario, PSFormatForDisplay debe usarse para dar formato al valor según la información regional y específica de la propiedad en lugar de usar PropVariantChangeType para convertir el valor en una cadena.

Ejemplos

En el ejemplo de código siguiente, que se va a incluir como parte de un programa más grande, se muestra cómo usar PropVariantChangeType para inicializar un valor de VT_FILETIME de una cadena.

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	Value
Cliente mínimo compatible	Windows XP con SP2, Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 con SP1 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	propvarutil.h
Library	Propsys.lib
Archivo DLL	Propsys.dll (versión 6.0 o posterior)
Redistribuible	Búsqueda de escritorio de Windows (WDS) 3.0