Метод IPropertyStorage::WriteMultiple (propidl.h)
Метод WriteMultiple записывает указанную группу свойств в текущий набор свойств. Если свойство с указанным именем или идентификатором свойства уже существует, оно заменяется, даже если старый и новый типы для значения свойства отличаются. Если свойство с заданным именем или идентификатором свойства не существует, оно создается.
Синтаксис
HRESULT WriteMultiple(
[in] ULONG cpspec,
[in] const PROPSPEC [] rgpspec,
[in] const PROPVARIANT [] rgpropvar,
[in] PROPID propidNameFirst
);
Параметры
[in] cpspec
Количество заданных свойств. Значение этого параметра можно задать равным нулю; однако это не позволяет использовать назначение метода, так как затем не записываются никакие свойства.
[in] rgpspec
Массив идентификаторов свойств (PROPSPEC), для которых заданы свойства. Они не должны быть в определенном порядке и могут содержать дубликаты, однако последний указанный идентификатор свойства вступает в силу. Допускается сочетание идентификаторов свойств и имен строк.
[in] rgpropvar
Массив ( размер cpspec) структур PROPVARIANT , содержащий значения свойств для записи. Массив должен иметь размер, заданный cpspec.
[in] propidNameFirst
Минимальное значение идентификаторов свойств, которые должен назначить метод, если параметр rgpspec указывает строковые свойства, для которых в настоящее время не существует идентификаторов свойств. Если все указанные строковые свойства уже существуют в этом наборе и, следовательно, имеют идентификаторы свойств, это значение игнорируется. Если это значение не игнорируется, это значение должно быть больше или равно двум и меньше 0x80000000. Идентификаторы свойств 0 и 1 и больше 0x80000000 зарезервированы для специального использования.
Возвращаемое значение
Этот метод поддерживает стандартное возвращаемое значение E_UNEXPECTED в дополнение к следующему:
Эта функция также может возвращать любые ошибки файловой системы или ошибки Win32, заключенные в тип данных HRESULT . Дополнительные сведения см. в разделе Стратегии обработки ошибок.
Комментарии
Если указанное свойство уже существует, его значение заменяется значением, указанным в rgpspec, даже если старый и новый типы для значения свойства отличаются. Если указанное свойство еще не существует, это свойство создается. Изменения не сохраняются в базовом хранилище, пока не будет вызван метод IPropertyStorage::Commit .
Имена свойств хранятся в специальном разделе словаря набора свойств, который сопоставляет такие имена с идентификаторами свойств. Все свойства имеют идентификатор, но имена являются необязательными. Строковое имя указывается путем указания PRSPEC_LPWSTR в элементе ulKind структуры PROPSPEC . Если строковое имя указано для свойства, а имя еще не существует в словаре, метод выделяет идентификатор свойства и добавляет идентификатор свойства и имя в словарь. Идентификатор свойства выделяется таким образом, чтобы не конфликтовать с другими идентификаторами в наборе свойств. Значение идентификатора свойства также не меньше значения, заданного параметром propidNameFirst . Если параметр rgpspec задает строковые свойства, для которых в настоящее время не существует идентификаторов свойств, параметр propidNameFirst задает минимальное значение идентификаторов свойств, которые должен назначить метод WriteMultiple .
При создании нового набора свойств специальные свойства codepage (Идентификатор свойства 1) и Locale ID (Идентификатор свойства 0x80000000) записываются в набор свойств автоматически. Эти свойства можно впоследствии считывать с помощью метода IPropertyStorage::ReadMultiple , указав идентификаторы свойств с заданными заголовками PID_CODEPAGE и PID_LOCALE значения соответственно. Если набор свойств не является пустым ( имеет одно или несколько свойств в дополнение к свойствам кодовой страницы и идентификатора языкового стандарта или имеет одно или несколько имен в словаре), специальные свойства codepage и locale ID нельзя изменить путем вызова IPropertyStorage::WriteMultiple. Однако если набор свойств пуст, можно изменить одно или оба из этих специальных свойств.
Если элементу в массиве rgspec задано PRSPEC_PROPID значение 0xffffffff (PID_ILLEGAL), то iPropertyStorage::WriteMultiple игнорирует соответствующее значение в массиве rgvar. Например, если этот метод вызывается с параметром cspec , равным 3, но rgpspec[1].prspec имеет значение PRSPEC_PROPID, а rgpspec[1].propid — PID_ILLEGAL, будут записаны только два свойства. Элемент rgpropvar[1] игнорируется без уведомления.
Используйте макрос PropVariantInit для инициализации структур PROPVARIANT .
Наборы свойств, не включая данные для неимпляционных свойств, ограничены размером 256 КБ для Windows NT 4.0 и более ранних версий. Для Windows 2000, Windows XP и Windows Server 2003 наборы свойств OLE ограничены 1 МБ. Если эти ограничения превышены, операция завершается сбоем, и вызывающий объект получает сообщение об ошибке. Нет никакой возможности утечки или переполнения памяти. Дополнительные сведения см. в разделе Управление наборами свойств.
Если PROPSETFLAG_CASE_SENSITIVE не передается в IPropertySetStorage::Create, имена наборов свойств не учитывают регистр. Указание свойства по его имени в IPropertyStorage::WriteMultiple приведет к поиску имен в наборе свойств без учета регистра. Чтобы сравнить строки без учета регистра, необходимо знать языковой стандарт строк. Дополнительные сведения см. в разделе IPropertyStorage::WritePropertyNames.
Дополнительные сведения см. в разделе Рекомендации по хранилищу свойств.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Профессиональная [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows 2000 Server [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | propidl.h (включая Objbase.h, Propidlbase.h) |
| Библиотека | Uuid.lib |
| DLL | Ole32.dll |