Функция PropVariantChangeType (propvarutil.h)

Статья
03/15/2023

Принудает значение, хранящееся в виде структуры PROPVARIANT , к эквивалентному значению другого типа варианта.

Синтаксис

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

Параметры

[out] ppropvarDest

Тип: PROPVARIANT*

Указатель на структуру PROPVARIANT , которая при успешном возврате этой функции получает принудованное значение и новый тип.

[in] propvarSrc

Тип: REFPROPVARIANT

Ссылка на исходную структуру PROPVARIANT , содержащую значение, выраженное в качестве исходного типа.

[in] flags

Тип: PROPVAR_CHANGE_FLAGS

Зарезервировано, должно быть 0.

[in] vt

Тип: VARTYPE

Указывает новый тип для значения. Имена распознаваемых типов см. в таблицах ниже.

Возвращаемое значение

Тип: HRESULT

Возвращает S_OK в случае успешного выполнения, или значение стандартной ошибки COM в противном случае. Если запрошенное приведение невозможно, возвращается ошибка.

Обратите внимание, что исходная и целевая структуры PROPVARIANT должны быть отдельными структурами. Невозможно перезаписать исходные данные PROPVARIANT новыми целевыми данными; Попытка сделать это приведет к ошибке.

PropVariantChangeType преобразует значения между следующими типами следующим образом. Числа относятся к условиям, объясняемых после таблиц.

	VT_LPWSTR	VT_BSTR	VT_BOOL.	VT_FILETIME	VT_DATE	VT_CLSID
VT_LPWSTR	Да	Да	Да	Да (2)	Да (2)	Да
VT_BSTR	Да	Да	Да	Да (2)	Да (2)	Да
VT_BOOL.	Да	Да	Да	Нет	Нет	Нет
VT_I2	Да	Да	Да	Нет	Нет	Нет
VT_I4	Да	Да	Да	Нет	Нет	Нет
VT_I8	Да	Да	Да	Нет	Нет	Нет
VT_UI2	Да	Да	Да	Нет	Нет	Нет
VT_UI4	Да	Да	Да	Нет	Нет	Нет
VT_UI8	Да	Да	Да	Нет	Нет	Нет
VT_R8	Да (3)	Да (3)	Да	Нет	Нет	Нет
VT_FILETIME	Да (2)	Да (2)	Нет	Да	Да	Нет
VT_DATE	Да (2)	Да (2)	Нет	Да	Да	Нет
VT_CLSID	Да	Да	Нет	Нет	Нет	Да

	VT_I2	VT_I4	VT_I8	VT_UI2	VT_UI4	VT_UI8	VT_R8
VT_LPWSTR	Да	Да	Да	Да	Да	Да	Да (3)
VT_BSTR	Да	Да	Да	Да	Да	Да	Да (3)
VT_BOOL.	Да	Да	Да	Да	Да	Да	Да
VT_I2	Да	Да	Да	Да (1)	Да (1)	Да (1)	Да (1)
VT_I4	Да (1)	Да	Да	Да (1)	Да (1)	Да (1)	Да (1)
VT_I8	Да (1)	Да (1)	Да	Да (1)	Да (1)	Да (1)	Да (1)
VT_UI2	Да (1)	Да	Да	Да	Да	Да	Да (1)
VT_UI4	Да (1)	Да (1)	Да	Да (1)	Да	Да	Да (1)
VT_UI8	Да (1)	Да (1)	Да (1)	Да (1)	Да (1)	Да	Да (1)
VT_R8	Да (1)	Да (1)	Да (1)	Да (1)	Да (1)	Да (1)	Да
VT_FILETIME	Нет	Нет	Нет	Нет	Нет	Нет	Нет
VT_DATE	Нет	Нет	Нет	Нет	Нет	Нет	Нет
VT_CLSID	Нет	Нет	Нет	Нет	Нет	Нет	Нет

Условия

При преобразовании между числовыми типами преобразования за пределы диапазона завершаются ошибкой. Например, отрицательное значение со знаком для типа без знака или 4-байтовое значение без знака больше 65535 до 2-байтового типа без знака.
При преобразовании между строками и датами используется каноническая строковая форма, а не локализованное или "удобочитаемое" представление. Формат : "гггг/мм/дд:чч:мм:сс.fff" (год, месяц, дата, часы, минуты, секунды, миллисекунды). Обратите внимание, что эта точность меньше, чем поддерживается типом FILETIME , но ее должно быть достаточно для большинства целей.
При преобразовании между числами с плавающей запятой и строками используется десятичный разделитель текущего языкового стандарта. Обратите внимание, что это может привести к проблемам при сохранении этих значений в файлах, перемещающихся между разными языковыми стандартами.

Примечание В будущем могут поддерживаться дополнительные типы.

В некоторых случаях поддерживается преобразование между векторами (VT_VECTOR) и массивами (VT_ARRAY). Если она поддерживается, количество элементов должно быть одинаковым в каждом из них. Однозначный вектор можно преобразовать в невекторное значение, но многозначный вектор нельзя преобразовать в невекторный тип.

Приведение между типами выполняется без учета сведений о свойствах. Приведение для конкретных свойств должно выполняться с помощью PSCoerceToCanonicalValue. Кроме того, если строковая форма значения необходима для целей пользовательского интерфейса, следует использовать PSFormatForDisplay для форматирования значения в соответствии со сведениями о языковом стандарте и свойстве, а не использовать PropVariantChangeType для приведение значения к строке.

Примеры

В следующем примере кода, который будет включен в состав более крупной программы, показано, как использовать PropVariantChangeType для инициализации VT_FILETIME значения из строки.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows XP с пакетом обновления 2 (SP2), Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2003 с пакетом обновления 1 (SP1) [только классические приложения]
Целевая платформа	Windows
Header	propvarutil.h
Библиотека	Propsys.lib
DLL	Propsys.dll (версия 6.0 или более поздняя)
Распространяемые компоненты	Windows Desktop Search (WDS) 3.0

Поделиться через