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

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

  • Статья

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

Синтаксис

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

Параметры

[in, out] ppropvar

Тип: PROPVARIANT*

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

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

Тип: HRESULT

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

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

Код возврата Описание
S_OK
 Функция выполнена успешно. Значение свойства, указанное ppropvar , теперь находится в канонической форме.
INPLACE_S_TRUNCATED
 Значение свойства, заданное ppropvar , теперь находится в усеченной канонической форме.
E_INVALIDARG
 Недопустимый параметр ppropvar . Структура 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.
     

Требования

Требование Значение
Минимальная версия клиента Windows Vista [только классические приложения]
Минимальная версия сервера Windows Server 2008 [только классические приложения]
Целевая платформа Windows
Header propsys.h

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

IPropertyDescription

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