Export (0) Print
Expand All
Expand Minimize

PropVariantChangeType function

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

Syntax


HRESULT PropVariantChangeType(
  _Out_  PROPVARIANT *ppropvarDest,
  _In_   REFPROPVARIANT propvarSrc,
  _In_   PROPVAR_CHANGE_FLAGS flags,
  _In_   VARTYPE vt
);

Parameters

ppropvarDest [out]

Type: PROPVARIANT*

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

propvarSrc [in]

Type: REFPROPVARIANT

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

flags [in]

Type: PROPVAR_CHANGE_FLAGS

Reserved, must be 0.

vt [in]

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_LPWSTRVT_BSTRVT_BOOLVT_FILETIMEVT_DATEVT_CLSID
VT_LPWSTRYesYesYesYes (2)Yes (2)Yes
VT_BSTRYesYesYesYes (2)Yes (2)Yes
VT_BOOLYesYesYesNoNoNo
VT_I2YesYesYesNoNoNo
VT_I4YesYesYesNoNoNo
VT_I8YesYesYesNoNoNo
VT_UI2YesYesYesNoNoNo
VT_UI4YesYesYesNoNoNo
VT_UI8YesYesYesNoNoNo
VT_R8Yes (3)Yes (3)YesNoNoNo
VT_FILETIMEYes (2)Yes (2)NoYesYesNo
VT_DATEYes (2)Yes (2)NoYesYesNo
VT_CLSIDYesYesNoNoNoYes

 

VT_I2VT_I4VT_I8VT_UI2VT_UI4VT_UI8VT_R8
VT_LPWSTRYesYesYesYesYesYesYes (3)
VT_BSTRYesYesYesYesYesYesYes (3)
VT_BOOLYesYesYesYesYesYesYes
VT_I2YesYesYesYes (1)Yes (1)Yes (1)Yes (1)
VT_I4Yes (1)YesYesYes (1)Yes (1)Yes (1)Yes (1)
VT_I8Yes (1)Yes (1)YesYes (1)Yes (1)Yes (1)Yes (1)
VT_UI2Yes (1)YesYesYesYesYesYes (1)
VT_UI4Yes (1)Yes (1)YesYes (1)YesYesYes (1)
VT_UI8Yes (1)Yes (1)Yes (1)Yes (1)Yes (1)YesYes (1)
VT_R8Yes (1)Yes (1)Yes (1)Yes (1)Yes (1)Yes (1)Yes
VT_FILETIMENoNoNoNoNoNoNo
VT_DATENoNoNoNoNoNoNo
VT_CLSIDNoNoNoNoNoNoNo

 

Conditions

  1. 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.
  2. 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.
  3. 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

Minimum supported client

Windows XP with SP2, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 with SP1 [desktop apps only]

Redistributable

Windows Desktop Search (WDS) 3.0

Header

Propvarutil.h

Library

Propsys.lib

DLL

Propsys.dll (version 6.0 or later)

 

 

Community Additions

ADD
Show:
© 2015 Microsoft