Метод IPropertyDescription::CoerceToCanonicalValue (propsys.h)

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

Синтаксис

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

Параметры

[in, out] ppropvar

Тип: PROPVARIANT*

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

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

Тип: HRESULT

Если код сбоя не INPLACE_S_TRUNCATED или E_INVALIDARG, то приведение типа значения к типу описания свойства было невозможно, и структура PROPVARIANT была очищена.

Возможные результаты:

Комментарии

Дополнительные сведения см. в описании атрибута type элемента typeInfo в PROPDESC-файле свойства.

Большинство описаний свойств указывают тип, который должны использоваться их значениями. Например, в описании свойства 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"Alice". Если это свойство дерева (то есть атрибут элемента isTreeProperty typeInfo имеет значение TRUE), то оно не должно иметь косую черту в начале или конце (/), не должно содержать пробелов между текстом и косой чертой и не должно иметь двух последовательных косых черт (/). Например L"Friend/Bob". Приведение удаляет ненужные символы и приводит к 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.

    

Требования

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

IPropertyDescription

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