PropVariantChangeType function (propvarutil.h)

Article
10/13/2021

Coerces a value stored as a PROPVARIANT structure to an equivalent value of a different variant type.

Syntax

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

Parameters

[out] ppropvarDest

Type: PROPVARIANT*

A pointer to a PROPVARIANT structure that, when this function returns successfully, receives the coerced value and its new type.

[in] propvarSrc

Type: REFPROPVARIANT

A reference to the source PROPVARIANT structure that contains the value expressed as its original type.

[in] flags

Type: PROPVAR_CHANGE_FLAGS

Reserved, must be 0.

[in] vt

Type: VARTYPE

Specifies the new type for the value. See the tables below for recognized type names.

Return value

Type: HRESULT

Returns S_OK if successful, or a standard COM error value otherwise. If the requested coercion is not possible, an error is returned.

Remarks

Note that the source and destination PROPVARIANT structures must be separate structures. You cannot overwrite the source PROPVARIANT data with the new destination data; attempting to do so will result in an error.

PropVariantChangeType converts values between the following types as follows. Numbers refer to conditions explained after the tables.

	VT_LPWSTR	VT_BSTR	VT_BOOL	VT_FILETIME	VT_DATE	VT_CLSID
VT_LPWSTR	Yes	Yes	Yes	Yes (2)	Yes (2)	Yes
VT_BSTR	Yes	Yes	Yes	Yes (2)	Yes (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	Yes (3)	Yes (3)	Yes	No	No	No
VT_FILETIME	Yes (2)	Yes (2)	No	Yes	Yes	No
VT_DATE	Yes (2)	Yes (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	Yes (3)
VT_BSTR	Yes	Yes	Yes	Yes	Yes	Yes	Yes (3)
VT_BOOL	Yes	Yes	Yes	Yes	Yes	Yes	Yes
VT_I2	Yes	Yes	Yes	Yes (1)	Yes (1)	Yes (1)	Yes (1)
VT_I4	Yes (1)	Yes	Yes	Yes (1)	Yes (1)	Yes (1)	Yes (1)
VT_I8	Yes (1)	Yes (1)	Yes	Yes (1)	Yes (1)	Yes (1)	Yes (1)
VT_UI2	Yes (1)	Yes	Yes	Yes	Yes	Yes	Yes (1)
VT_UI4	Yes (1)	Yes (1)	Yes	Yes (1)	Yes	Yes	Yes (1)
VT_UI8	Yes (1)	Yes (1)	Yes (1)	Yes (1)	Yes (1)	Yes	Yes (1)
VT_R8	Yes (1)	Yes (1)	Yes (1)	Yes (1)	Yes (1)	Yes (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

Conditions

When converting between numeric types, out-of-range conversions fail. For instance, a negative signed value to an unsigned type, or a 4-byte unsigned value larger than 65535 to a 2-byte unsigned type.
When converting between strings and dates, a canonical string form is used rather than a localized or "human-readable" representation. The format is "yyyy/mm/dd:hh:mm:ss.fff" (year, month, date, hours, minutes, seconds, milliseconds). Note that this is less precision than is supported by the FILETIME type, but it should be sufficient for most purposes.
When converting between floating point numbers and strings, the current locale's decimal separator is used. Note that this might cause problems when these values are saved in files that are moved between different locales.

Note Additional types might be supported in the future.

Converting between vectors (VT_VECTOR) and arrays (VT_ARRAY) is supported in some cases. When it is supported, the count of elements must be the same in each. A single-valued vector can be converted to a non-vector value, but a multi-valued vector cannot be converted to a non-vector type.

Coercion between types is performed without respect to property-specific information. Property-specific coercions should be performed using PSCoerceToCanonicalValue. Additionally, if the string form of a value is needed for UI purposes, PSFormatForDisplay should be used to format the value according to locale- and property-specific information rather than using PropVariantChangeType to coerce the value to a string.

Examples

The following code example, to be included as part of a larger program, demonstrates how to use PropVariantChangeType to initialize a VT_FILETIME value from a string.

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);
}

Requirements

Requirement	Value
Minimum supported client	Windows XP with SP2, Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 with SP1 [desktop apps only]
Target Platform	Windows
Header	propvarutil.h
Library	Propsys.lib
DLL	Propsys.dll (version 6.0 or later)
Redistributable	Windows Desktop Search (WDS) 3.0

Share via