IPropertyStorage：：WriteMultiple 方法 (propidl.h)

项目
03/01/2024

WriteMultiple 方法将指定的属性组写入当前属性集。如果具有指定名称或属性标识符的属性已存在，则即使属性值的旧类型和新类型不同，也会替换该属性。如果给定名称或属性 ID 的属性不存在，则创建该属性。

语法

HRESULT WriteMultiple(
  [in] ULONG                cpspec,
  [in] const PROPSPEC []    rgpspec,
  [in] const PROPVARIANT [] rgpropvar,
  [in] PROPID               propidNameFirst
);

参数

[in] cpspec

设置的属性数。此参数的值可以设置为零;但是，这违背了方法的用途，因为随后不会写入任何属性。

[in] rgpspec

属性 ID (PROPSPEC) 属性设置为的数组。这些属性不需要采用任何特定顺序，并且可能包含重复项，但最后指定的属性 ID 是生效的属性 ID。允许混合使用属性 ID 和字符串名称。

[in] rgpropvar

包含要写入的属性值的 PROPVARIANT 结构的大小 () cpspec 的数组。数组必须是 cpspec 指定的大小。

[in] propidNameFirst

如果 rgpspec 参数指定了当前不存在任何属性 ID 的字符串命名属性，则为方法必须分配的属性 ID 的最小值。如果此集中已存在所有以字符串命名的属性，因此已具有属性 ID，则忽略此值。如果未忽略，此值必须大于或等于 2 且小于 0x80000000。属性 ID 0 和 1 以及大于 0x80000000 保留供特殊使用。

返回值

此方法支持E_UNEXPECTED的标准返回值，此外还支持以下各项：

此函数还可以返回包装在 HRESULT 数据类型中的任何文件系统错误或 Win32 错误。有关详细信息，请参阅错误处理策略。

注解

如果指定的属性已存在，则其值将替换为 rgpspec 中指定的值，即使属性值的旧类型和新类型不同也是如此。如果指定的属性尚不存在，则会创建该属性。在调用 IPropertyStorage：：Commit 之前，更改不会保存到基础存储中。

属性名称存储在属性集的特殊字典部分中，该字典部分将此类名称映射到属性 ID。所有属性都有一个 ID，但名称是可选的。通过在 PROPSPEC 结构的 ulKind 成员中指定PRSPEC_LPWSTR来提供字符串名称。如果为属性提供了字符串名称，并且字典中尚不存在该名称，则该方法将分配属性 ID，并将属性 ID 和名称添加到字典中。属性 ID 的分配方式是，它不会与属性集中的其他 ID 冲突。属性 ID 的值也不小于 propidNameFirst 参数指定的值。如果 rgpspec 参数指定当前不存在任何属性 ID 的字符串命名属性， 则 propidNameFirst 参数将指定 WriteMultiple 方法必须分配的属性 ID 的最小值。

创建新属性集时， (属性 ID 1) 的特殊代码页和区域设置 ID (属性 ID 0x80000000) 属性将自动写入属性集。随后可以使用 IPropertyStorage：：ReadMultiple 方法读取这些属性，方法是分别使用标头定义的PID_CODEPAGE和PID_LOCALE值指定属性 ID。如果属性集为非空（除代码页和区域设置 ID 属性外还有一个或多个属性，或者在其字典中具有一个或多个名称），则无法通过调用 IPropertyStorage：：WriteMultiple 来修改特殊代码页和区域设置 ID 属性。但是，如果属性集为空，则可以修改其中一个或两个特殊属性。

如果 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 结构。

对于 Windows NT 4.0 及更早版本，属性集（不包括非简单属性的数据）的大小限制为 256 KB。对于 Windows 2000、Windows XP 和 Windows Server 2003，OLE 属性集限制为 1 MB。如果超出这些限制，操作将失败，调用方将收到错误消息。不存在内存泄漏或溢出的可能性。有关详细信息，请参阅管理属性集。

除非将PROPSETFLAG_CASE_SENSITIVE传递给 IPropertySetStorage：：Create，否则属性集名称不区分大小写。在 IPropertyStorage：：WriteMultiple 中按名称指定属性将导致对属性集中的名称进行不区分大小写的搜索。若要比较不区分大小写的字符串，字符串的区域设置必须是已知的。有关详细信息，请参阅 IPropertyStorage：：WritePropertyNames。

有关详细信息，请参阅属性存储注意事项。

要求

要求	值
最低受支持的客户端	Windows 2000 专业版 [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows 2000 Server [桌面应用 \|UWP 应用]
目标平台	Windows
标头	propidl.h (包括 Objbase.h、Propidlbase.h)
Library	Uuid.lib
DLL	Ole32.dll