Метод IPropertyStorage::WriteMultiple (propidl.h)

Статья
08/25/2023

Метод 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