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

[アーティクル]
08/25/2023

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) プロパティがプロパティセットに自動的に書き込まれます。これらのプロパティは、後で IPropertyStorage::ReadMultiple メソッドを使用して、ヘッダー定義のPID_CODEPAGEとPID_LOCALE値を持つプロパティ ID をそれぞれ指定することで読み取ることができます。プロパティセットが空でない場合、には、コードページとロケール 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 マクロを使用します。

プロパティセットは、非シンプルプロパティのデータを含めず、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 Professional [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	propidl.h (Objbase.h、Propidlbase.h を含む)
Library	Uuid.lib
[DLL]	Ole32.dll