IPropertyStorage：：WriteMultiple 方法 (propidl.h)

發行項
03/09/2024

WriteMultiple 方法會將指定的屬性群組寫入目前屬性集。如果具有指定名稱或屬性標識符的屬性已經存在，即使屬性值的舊型別和新型別不同，也會加以取代。如果指定名稱或屬性標識碼的屬性不存在，則會建立它。

語法

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

參數

[in] cpspec

已設定的屬性數目。此參數的值可以設定為零;不過，這會使方法的用途失效，因為接著不會寫入任何屬性。

[in] rgpspec

屬性標識碼的陣列， (PROPSPEC) 要設定的屬性。這些不需要任何特定順序，而且可能包含重複專案，但最後一個指定的屬性標識碼是生效的屬性標識符。允許混合屬性識別碼和字串名稱。

[in] rgpropvar

包含要寫入之屬性值的 PROPVARIANT 結構大小 cpspec) (陣列。陣列必須是 cpspec 所指定的大小。

[in] propidNameFirst

如果 rgpspec 參數指定目前不存在任何屬性識別碼的字串命名屬性，則方法必須指派的屬性識別碼的最小值。如果指定的所有字串命名屬性都已存在於此集合中，因此已有屬性識別碼，則會忽略此值。當未忽略時，此值必須大於或等於 2，且小於 0x80000000。屬性標識碼 0 和 1 和大於 0x80000000會保留供特殊使用。

傳回值

除了下列專案之外，這個方法還支援標準傳回值E_UNEXPECTED：

此函式也可以傳回任何檔案系統錯誤或 包裝在 HRESULT 資料類型中的 Win32 錯誤。如需詳細資訊，請參閱錯誤處理策略。

備註

如果指定的屬性已經存在，則會將其值取代為 rgpspec 中指定的值，即使屬性值的舊型別和新類型不同也一樣。如果指定的屬性不存在，則會建立該屬性。在呼叫 IPropertyStorage：：Commit 之前，這些變更不會保存到基礎記憶體。

屬性名稱會儲存在屬性集的特殊字典區段中，其會將這類名稱對應至屬性標識元。所有屬性都有標識碼，但名稱是選擇性的。字串名稱是在 PROPSPEC 結構的 ulKind 成員中指定PRSPEC_LPWSTR來提供。如果為屬性提供字串名稱，且名稱不存在於字典中，則方法會配置屬性標識元，並將屬性標識碼和名稱新增至字典。屬性標識碼會以與屬性集中的其他標識符不衝突的方式配置。屬性標識碼的值也不小於 propidNameFirst 參數所指定的值。如果 rgpspec 參數指定目前沒有屬性識別碼的字串命名屬性， propidNameFirst 參數會指定 WriteMultiple 方法必須指派之屬性識別符的最小值。

建立新的屬性集時，會自動將特殊代碼頁 (屬性標識碼 1) 和地區設定標識碼 (屬性識別碼0x80000000 ) 屬性自動寫入屬性集。這些屬性接著可以使用 IPropertyStorage：：ReadMultiple 方法來讀取，方法是分別使用標頭定義的PID_CODEPAGE和PID_LOCALE值來指定屬性標識符。如果屬性集不是空的— 除了代碼頁和地區設定標識符屬性之外，還有一或多個屬性，或在其字典中有一或多個名稱，則無法藉由呼叫 IPropertyStorage：：WriteMultiple 來修改特殊代碼頁和地區設定標識符屬性。不過，如果屬性集是空的，則可以修改其中一個或兩個特殊屬性。

如果 rgspec 陣列中的專案是以0xffffffff (PID_ILLEGAL) 的PRSPEC_PROPID值設定，則 IPropertyStorage：：WriteMultiple 會忽略 rgvar 陣組中的對應值。例如，如果使用 cspec 參數設定為 3 呼叫此方法，但 rgpspec[1].prspec 設定為 PRSPEC_PROPID，而 rgpspec[1].propid 設定為 PID_ILLEGAL，則只會寫入兩個屬性。 rgpropvar[1] 元素會以無訊息方式忽略。

使用 PropVariantInit 宏初始化 PROPVARIANT 結構。

屬性集，不包括非簡單屬性的數據，大小限制為 256 KB，Windows NT 4.0 和更早版本。針對 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)
程式庫	Uuid.lib
Dll	Ole32.dll