IPropertyStorage::WriteMultiple メソッド (propidlbase.h)

[アーティクル]
03/05/2024

WriteMultiple メソッドは、指定したプロパティグループを現在のプロパティセットに書き込みます。指定した名前またはプロパティ識別子を持つプロパティが既に存在する場合は、プロパティ値の古い型と新しい型が異なる場合でも置き換えられます。指定された名前またはプロパティ ID のプロパティが存在しない場合は、作成されます。

構文

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

パラメーター

[in] cpspec

プロパティセットの数。このパラメーターの値は 0 に設定できます。ただし、これはプロパティが書き込まれず、メソッドの目的を損ないます。

[in] rgpspec

プロパティが設定されるプロパティ ID (PROPSPEC) の配列。これらは特定の順序である必要はありません。重複を含む場合がありますが、最後に指定されたプロパティ 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) プロパティがプロパティセットに自動的に書き込まれます。これらのプロパティは、ヘッダーで定義されたPID_CODEPAGEとPID_LOCALEの値をそれぞれ使用してプロパティ ID を指定することで、 IPropertyStorage::ReadMultiple メソッドを使用して読み取ることができます。プロパティセットが空でない場合は、コードページとロケール ID プロパティに加えて 1 つ以上のプロパティを持つ場合、またはディクショナリに 1 つ以上の名前がある場合、IPropertyStorage::WriteMultiple を呼び出して特別なコードページとロケール ID プロパティを変更することはできません。ただし、プロパティセットが空の場合は、これらの特別なプロパティの一方または両方を変更できます。

rgspec 配列内の要素が 0xffffffff (PID_ILLEGAL) のPRSPEC_PROPID値で設定されている場合、rgvar 配列の対応する値は IPropertyStorage::WriteMultiple によって無視されます。たとえば、 cspec パラメーターを 3 に設定してこのメソッドを呼び出したが、 rgpspec[1].prspec が PRSPEC_PROPID に設定され、 rgpspec[1].propid がPID_ILLEGALに設定されている場合、2 つのプロパティのみが書き込まれます。 rgpropvar[1] 要素は無視されます。

PROPVARIANT 構造体を初期化するには、PropVariantInit マクロを使用します。

プロパティセットは、非シンプルプロパティのデータを含めず、4.0 以前Windows NT 256 KB のサイズに制限されます。 Windows 2000、Windows XP、Windows Server 2003 の場合、OLE プロパティセットは 1 MB に制限されます。これらの制限を超えると、操作は失敗し、呼び出し元はエラーメッセージを受け取ります。メモリリークやオーバーランの可能性はありません。詳細については、「プロパティセットの管理」を参照してください。

PROPSETFLAG_CASE_SENSITIVEが IPropertySetStorage::Create に渡されない限り、プロパティセット名では大文字と小文字が区別されません。 IPropertyStorage::WriteMultiple でプロパティの名前でプロパティを指定すると、プロパティセット内の名前が大文字と小文字を区別せずに検索されます。大文字と小文字を区別しない文字列を比較するには、文字列のロケールがわかっている必要があります。詳細については、「 IPropertyStorage::WritePropertyNames」を参照してください。

詳細については、「プロパティストレージに関する考慮事項」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	propidlbase.h (Objbase.h、Propidlbase.h を含む)
Library	Uuid.lib
[DLL]	Ole32.dll