IPropertyStorage::WriteMultiple 方法 (propidlbase.h)

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

一个数组 (大小 cpspec) 包含要写入的属性值的 PROPVARIANT 结构。 数组必须是 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) 区域设置 ID (属性 ID 0x80000000) 属性自动写入属性集。 随后可以使用 IPropertyStorage::ReadMultiple 方法读取这些属性,方法是分别使用标头定义的PID_CODEPAGE和PID_LOCALE值指定属性 ID。 如果属性集为非空 (除 codepageLocale 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
标头 propidlbase.h (包括 Objbase.h、Propidlbase.h)
Library Uuid.lib
DLL Ole32.dll

另请参阅

IPropertySetStorage::Create

IPropertyStorage

IPropertyStorage::ReadMultiple

管理属性集

PROPVARIANT

示例

StgCreatePropSetStg 示例

WriteRead 示例