Функция PSCoerceToCanonicalValue (propsys.h)

Преобразует значение свойства в каноническое значение в соответствии с описанием свойства.

Синтаксис

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

Параметры

[in] key

Тип: REFPROPERTYKEY

Ссылка на структуру PROPERTYKEY , идентифицирующая свойство, значение которого должно быть принудено.

[in, out] ppropvar

Тип: PROPVARIANT*

В элементе содержит указатель на структуру PROPVARIANT , содержащую исходное значение. При успешном возвращении этой функции содержит каноническое значение.

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

Тип: HRESULT

Возможные возвращаемые значения:

Код возврата	Описание
S_OK	Функция выполнена успешно. Значение свойства, заданное ppropvar , теперь находится в канонической форме.
INPLACE_S_TRUNCATED	Значение свойства, заданное ppropvar , теперь находится в усеченной канонической форме.
E_INVALIDARG	Недопустимый параметр ppropvar . Структура PROPVARIANT была очищена.
TYPE_E_TYPEMISMATCH	Приведение типа значения к типу описания свойства невозможно. Структура PROPVARIANT была очищена.
Любой другой код сбоя	Приведение типа значения к типу описания свойства невозможно. Структура PROPVARIANT была очищена.

Комментарии

Эта функция является оболочкой для системной реализации IPropertyDescription::CoerceToCanonicalValue.

В большинстве описаний свойств указывается тип, который должны использоваться их значениями. Например, в описании свойства System.Title указано, что значения System.Title должны быть типа VT_LPWSTR. Эта функция приводит значения к этому типу, а затем приводит результат в каноническую форму.

Важно отметить, что в случае сбоя этой функции она уже вызовет PropVariantClear для входной структуры PROPVARIANT . Только в случае успешного выполнения этой функции вызывается приложение, ответственное за вызов PropVariantClear в ppropvar , когда структура больше не нужна.

Приведение, выполняемое этой функцией, также выполняется системой свойств во время вызовов IPropertyStore::GetValue и IPropertyStore::SetValue. Приложения могут зависеть от системы свойств для выполнения приведения или использовать эту функцию для выполнения приведения в момент выбора приложения.

Приведение выполняется в четыре этапа следующим образом:

1. Следующие значения преобразуются в VT_EMPTY.
   • Значения типа VT_NULL.
   • Значения типа VT_LPWSTR, VT_BSTR или VT_LPSTR с указателем NULL.
   • Значения типа VT_LPWSTR, VT_BSTR или VT_LPSTR, которые являются пустыми или полностью состоят из пробелов.
   • Значения типа VT_FILETIME до полуночи 1601/01/02.
2. Если значение не относится к типу VT_EMPTY после шага 1, оно преобразуется в тип, указанный в описании свойства. Тип описания свойства можно получить, вызвав IPropertyDescription::GetPropertyType. Сведения о том, как схема свойств влияет на тип описания свойства, см. в разделе typeInfo. Преобразования выполняются следующим образом:
   • Значения типа VT_LPWSTR, VT_BSTR или VT_LPSTR преобразуются в VT_VECTOR | VT_LPWSTR с помощью InitPropVariantFromStringAsVector.
   • Все остальные преобразования выполняются с помощью PropVariantChangeType.
3. После шагов 2 и 3 значение преобразуется в каноническую форму на основе его типа. Канонические формы приведены в следующей таблице.

   Тип значения	Каноническая форма
   VT_EMPTY	Всегда канонический.
   VT_LPWSTR	Нет начальных или конечных пробелов. Строка не пуста и не имеет значения NULL. Например, L "Алиса". Если это свойство дерева (то есть атрибут isTreeProperty элемента typeInfo имеет значение TRUE), то оно не должно иметь косую черту в начале или конце (/), не должно иметь пробелов между текстом и косой чертой и не должно иметь двух последовательных косых черт (/). Например, L "Друг/Боб". Приведение удаляет ненужные символы и приводит к VT_EMPTY, если содержимое отсутствует.
   VT_VECTOR | VT_LPWSTR	Каждая строка в векторе должна соответствовать правилам для VT_LPWSTR, перечисленным выше. Кроме того, вектор не должен иметь дубликатов и пустых указателей. Если это свойство дерева, то никакое значение не может быть предком другого значения. Например, L "Friend" является предком L "Друг/Боб". Если содержимое отсутствует, приведение удаляет повторяющиеся символы и символы-предки и приводит к VT_EMPTY.

    
4. Если применимо, значение проверяется в соответствии с перечислением типов описания свойства. Применяются проверки, приведенные в следующей таблице.

   Тип перечисления	Тип значения	Каноническая форма
   Дискретный или диапазонный	VT_EMPTY	Всегда канонический
   Discrete	VT_LPWSTR	Строка соответствует одной из перечисленных строк, разрешенных для свойства . Сравнения выполняются без учета регистра. В противном случае преобразуйте значение в VT_EMPTY.
   Discrete	Числовой	Число соответствует одному из перечисленных значений, разрешенных для свойства . В противном случае преобразуйте значение в VT_EMPTY.
   Discrete	VT_VECTOR | VT_LPWSTR	Каждая строка в векторе соответствует одной из перечисленных строк, разрешенных для свойства . Сравнения выполняются без учета регистра. В противном случае удалите эту строку из вектора. Если результирующий вектор пуст, преобразуйте значение в VT_EMPTY.
   Discrete	VT_VECTOR | Числовые	Каждое число в векторе соответствует одному из перечисленных значений, допустимых для свойства . В противном случае удалите это число из вектора. Если результирующий вектор пуст, преобразуйте значение в VT_EMPTY.
   Колебалась	VT_LPWSTR	Строка существует в диапазоне, разрешенном для свойства . При сравнениях учитывается регистр. В противном случае преобразуйте значение в VT_EMPTY.
   Колебалась	Числовой	Число существует в диапазоне, разрешенном для свойства . В противном случае преобразуйте значение в VT_EMPTY.
   Колебалась	VT_VECTOR | VT_LPWSTR	Каждая строка в векторе существует в диапазоне, разрешенном для свойства . При сравнениях учитывается регистр. В противном случае удалите эту строку из вектора. Если результирующий вектор пуст, преобразуйте значение в VT_EMPTY.
   Колебалась	VT_VECTOR | Числовые	Каждое число в векторе находится в диапазоне, разрешенном для свойства . В противном случае удалите это число из вектора. Если результирующий вектор пуст, преобразуйте значение в VT_EMPTY.

    

Примеры

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

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

Требования

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

См. также раздел

IPropertyDescription

IShellItem2::GetPropertyStore

PropVariantChangeType

Схема описания свойства

Typeinfo