IPropertyStorage

IPropertyStorage インターフェイスは、単一のプロパティセットの永続的なプロパティを管理します。(IPropertyStorage interface)

IPropertyStorage::ReadMultiple メソッドは、現在のプロパティセットから指定されたプロパティを読み取ります。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

この関数は、HRESULT データ型にラップされたファイルシステムエラーや Win32 エラーを返すこともあります。詳細については、 エラー処理の方針を参照してください。

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

IPropertyStorage::WriteMultiple メソッドは、指定されたプロパティのグループを現在のプロパティセットに書き込みます。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

この関数は、HRESULT データ型にラップされたファイルシステムエラーや Win32 エラーを返すこともあります。詳細については、 エラー処理の方針を参照してください。

指定されたプロパティが既に存在する場合、その値は rgpspec で指定された値で置き換えられます。これは、そのプロパティ値の古い型と新しい型が異なる場合でも同様です。指定されたプロパティがまだ存在しない場合は、そのプロパティが作成されます。これらの変更は、IPropertyStorage::Commit が呼び出されるまで、基になるストレージには永続化されません。

プロパティ名は、プロパティセットの特別なディクショナリセクションに格納され、これらの名前をプロパティ ID にマッピングします。すべてのプロパティには ID がありますが、名前は任意です。文字列名は、 PROPSPEC 構造体の ulKind メンバーに PRSPEC_LPWSTR を指定することで指定します。プロパティに文字列名が指定され、その名前がディクショナリにまだ存在しない場合、メソッドはプロパティ ID を割り当て、そのプロパティ ID と名前をディクショナリに追加します。プロパティ ID は、プロパティセット内の他の ID と競合しないように割り当てられます。プロパティ ID の値は、propidNameFirst パラメーターで指定された値以上にもなります。rgpspec パラメーターが、現在プロパティ ID の存在しない文字列名付きプロパティを指定している場合、propidNameFirst パラメーターは、 WriteMultiple メソッドが割り当てなければならないプロパティ ID の最小値を指定します。

新しいプロパティセットが作成されると、特別な codepage(プロパティ ID 1) および ロケール ID(プロパティ ID 0x80000000) の各プロパティが、プロパティセットに自動的に書き込まれます。これらのプロパティは、その後、IPropertyStorage::ReadMultiple メソッドを使用し、ヘッダーで定義された PID_CODEPAGE 値と PID_LOCALE 値でそれぞれプロパティ ID を指定することで読み取れます。プロパティセットが空でない場合、つまり codepage および ロケール ID プロパティに加えて 1 つ以上のプロパティを持つか、ディクショナリに 1 つ以上の名前を持つ場合、特別な codepage および ロケール ID プロパティは IPropertyStorage::WriteMultiple の呼び出しでは変更できません。ただし、プロパティセットが空であれば、これらの特別なプロパティの一方または両方を変更できます。

rgspec 配列の要素が PRSPEC_PROPID の値 0xffffffff(PID_ILLEGAL)で設定されている場合、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 を参照してください。

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

IPropertyStorage::DeleteMultiple メソッドは、指定されたプロパティのうち、プロパティセットに存在するものをできる限り多く削除します。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

IPropertyStorage::DeleteMultiple は、指定されたプロパティのうち、現在のプロパティセットに存在するものをできる限り多く削除しなければなりません。ストリーム値またはストレージ値を持つプロパティが開かれている間にその削除が行われた場合、削除は成功し、以前に返された IStream または IStorage ポインターを reverted 状態にします。

IPropertyStorage::ReadPropertyNames メソッドは、指定されたプロパティ ID に対して既存の文字列名がある場合、それらを取得します。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

rgpropid 配列で指定されたプロパティ ID のリスト内の各プロパティ ID について、ReadPropertyNames は、対応する文字列名が存在すればそれを取得します。文字列名は、プロパティを作成する際の IPropertyStorage::WriteMultiple の呼び出しで名前を指定するか、IPropertyStorage::WritePropertyNames の呼び出しによって作成されます。いずれの場合も、文字列名は任意ですが、すべてのプロパティにはプロパティ ID が必要です。

プロパティ ID にマッピングされる文字列名は、セット内で一意でなければなりません。

IPropertyStorage::WritePropertyNames メソッドは、現在のプロパティセット内の指定されたプロパティ ID の配列に文字列名を割り当てます。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

プロパティセットとメモリ管理の詳細については、 プロパティセットの管理を参照してください。

IPropertyStorage::WritePropertyNames は、rgpropid 配列でメソッドに渡されたプロパティ ID に文字列名を割り当てます。rglpwstrName 配列内の各文字列名を、rgpropid 内のそれぞれのプロパティ ID に関連付けます。現在プロパティストレージオブジェクトに存在しないプロパティ ID に対して名前を定義することは、明示的に有効です。

また、既存の文字列名のマッピングを変更することも有効です(大文字と小文字を区別しない一致で判定されます)。つまり、 WritePropertyNames メソッドを使用して、既存の名前を新しいプロパティ ID にマッピングしたり、ディクショナリに既に名前を持つプロパティ ID に新しい名前をマッピングしたりできます。いずれの場合も、元のマッピングは削除されます。プロパティ名は、プロパティセット内で(プロパティ ID と同様に)一意でなければなりません。

文字列プロパティ名の格納では大文字と小文字が保持されます。PROPSETFLAG_CASE_SENSITIVE が IPropertySetStorage::Create に渡されていない限り、プロパティセット名は既定で大文字と小文字を区別しません。大文字と小文字を区別しないプロパティセットでは、呼び出し側が渡す名前文字列は、PID_LOCALE プロパティで指定されたプロパティセットのロケールに従って解釈されます。プロパティセットにロケールプロパティがない場合は、既定で現在のユーザーが想定されます。文字列プロパティ名の長さは 128 文字に制限されています。バイナリの Unicode 文字 0x0001 から 0x001F で始まるプロパティ名は、将来の使用のために予約されています。

rgpropid 配列パラメーター内の要素の値が 0xffffffff(PID_ILLEGAL)に設定されている場合、対応する名前は IPropertyStorage::WritePropertyNames によって無視されます。たとえば、このメソッドが cpropid パラメーター 3 で呼び出されたが、配列の最初の要素 rgpropid[1] が PID_ILLEGAL に設定されている場合、書き込まれるプロパティ名は 2 つだけになります。rgpropid[1] 要素は無視されます。

IPropertyStorage::DeletePropertyNames メソッドは、現在のプロパティセットから指定された文字列名を削除します。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

rgpropid 内の各プロパティ識別子について、IPropertyStorage::DeletePropertyNames は、対応する名前とプロパティ ID のマッピングをすべて削除します。存在しないプロパティ、または現在文字列名が関連付けられていないプロパティの名前を削除しようとしても、暗黙的に無視されます。このメソッドは、プロパティそのものには影響しません。

IPropertyStorage::Commit メソッドは、プロパティストレージオブジェクトに加えられた変更を親ストレージオブジェクトに保存します。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

IStorage::Commit と同様に、IPropertyStorage::Commit メソッドは、プロパティストレージオブジェクトに加えられた変更が親ストレージに反映されることを保証します。

複合ファイル実装のダイレクトモードでは、このメソッドの呼び出しにより、現在メモリバッファーにある変更が基になるプロパティストリームにフラッシュされます。非単純プロパティセットの複合ファイル実装では、渡された grfCommitFlags パラメーターとともに、基になるサブストレージオブジェクトに対しても IStorage::Commit が呼び出されます。

トランザクションモードでは、このメソッドにより、変更がストレージオブジェクトの永続的なイメージに恒久的に反映されます。コミットされる変更は、このプロパティセットが開かれてから、またはこのプロパティセットの現在の開いてからの最後のコミット以降に加えられたものでなければなりません。commit メソッドは、あるオブジェクトレベルで加えられた変更を次のレベルに公開します。もちろん、これは、このプロパティセットを含むオブジェクトに存在する可能性のある外側レベルのトランザクションの影響を受けます。コミット操作が成功するには、プロパティセットが(IPropertySetStorage を通じて)開かれる際に、そのプロパティセットの開くときに書き込み権限が指定されていなければなりません。

コミット操作が何らかの理由で失敗した場合、プロパティストレージオブジェクトの状態はコミット前のまま維持されます。

この呼び出しは、このプロパティストレージから開かれた既存のストレージ値またはストリーム値のプロパティには影響しませんが、それらをコミットはします。

grfCommitFlags パラメーターに有効な値を次の表に示します。

IPropertyStorage::Revert メソッドは、名前付きプロパティセットが最後に開かれてから加えられたすべての変更を破棄するか、プロパティセットに最後にコミットされた変更を破棄します。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

トランザクションモードのプロパティセットでは、このメソッドは、このプロパティセットが開かれてから、またはそれが最後にコミットされた時点(いずれか遅い方)以降にこのプロパティセットに加えられたすべての変更を破棄します。この操作の後、reverted されるプロパティセットから開かれていた既存のストレージ値またはストリーム値のプロパティは、もはや有効ではなくなり、使用できなくなります。これらのストリームまたはストレージを使用する呼び出しは、Release への呼び出しを除いて、すべてエラー STG_E_REVERTED を返します。

ダイレクトモードのプロパティセットでは、この要求は無視され、S_OK を返します。

IPropertyStorage::Enum メソッドは、現在のプロパティセットに関する情報を格納する STATPROPSTG 型のデータを列挙するために設計された列挙子オブジェクトを作成します。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

IPropertyStorage::Enum は、 STATPROPSTG 構造体を反復処理するために使用できる列挙オブジェクトを作成します。戻り時に、このメソッドは、このオブジェクト上の IEnumSTATPROPSTG インターフェイスのインスタンスへのポインターを提供します。そのメソッドを呼び出して、現在のプロパティセットに関する情報を取得できます。

IPropertyStorage::SetTimes メソッドは、実装がサポートしている場合、このプロパティセットの変更、アクセス、作成の各時刻を設定します。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

実装がサポートしている場合、現在開いているプロパティセットの変更、アクセス、作成の各時刻を設定します(すべての実装がこれらすべての時刻値をサポートしているわけではありません)。サポートされていないタイムスタンプは常に 0 として報告されるため、呼び出し側はサポートの有無をテストできます。IPropertyStorage::Stat の呼び出しは、(他のデータと合わせて)タイムスタンプ情報を提供します。

この機能は、 IPropertySetStorage のメソッドとして提供されるのではなく、既に開かれているプロパティストレージオブジェクトに対する IPropertyStorage メソッドとして提供されている点に注意してください。通常、 SetTimes メソッドが明示的に呼び出されない場合、アクセス時刻と変更時刻は、プロパティセットの読み取りや書き込みの副作用として更新されます。 SetTimes が使用されると、最後に指定された時刻が、既定の時刻または以前の SetTimes の呼び出しで指定された時刻値に優先します。

IPropertyStorage::SetClass メソッドは、現在のプロパティストレージオブジェクトに新しい CLSID を割り当て、その CLSID をオブジェクトとともに永続的に格納します。

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

現在のプロパティストレージオブジェクトに CLSID を割り当てます。CLSID は、格納されているプロパティ ID とは関係ありません。CLSID を割り当てることで、あるコードをプロパティセットの特定のインスタンスに関連付けることができます。たとえば、そのようなコードは、ユーザーインターフェイス(UI)を管理する場合があります。同じ FMTID を持つ異なるプロパティセットインスタンスに、異なる CLSID を関連付けることができます。

IPropertySetStorage::Create メソッドの pclsid パラメーターを NULL として指定してプロパティセットが作成された場合、CLSID はすべて 0 に設定されます。

プロパティストレージオブジェクトの現在の CLSID は、 IPropertyStorage::Stat の呼び出しで取得できます。CLSID の初期値は、IPropertySetStorage::Create の呼び出しでストレージを作成する際に指定できます。

非単純プロパティセット(IPropertySetStorage::Create で説明されているように、ストレージ値またはストリーム値のプロパティを合法的に含めることができるもの)に CLSID を設定すると、基になるサブストレージにも CLSID が設定されます。

IPropertyStorage::Stat メソッドは、現在開いているプロパティセットに関する情報を取得します。(IPropertyStorage.Stat)

このメソッドは、標準の戻り値 E_UNEXPECTED に加えて、次の戻り値をサポートします。

IPropertyStorage::Stat は、現在のプロパティセットに関する統計情報を格納する STATPROPSETSTG 構造体を埋めて、それへのポインターを返します。