Share via

IPropertyStorage-Compound ファイルの実装

  • [アーティクル]

構造化ストレージ アーキテクチャの COM 実装は、 複合ファイルと呼ばれます。 複合ファイルに実装されるストレージ オブジェクトには、単一の永続プロパティ セットを管理するインターフェイス である IPropertyStorage と、永続プロパティ セットのグループを管理するインターフェイス である IPropertySetStorage の両方の実装が含まれます。 IPropertyStorage インターフェイスの詳細については、「IPropertyStorage と Property Storage の考慮事項」を参照してください。

IPropertyStorage の複合ファイル実装へのポインターを取得するには、StgCreateStorageEx を呼び出して新しい複合ファイル オブジェクトを作成するか、StgOpenStorageEx を呼び出して、以前に作成した複合ファイル オブジェクトを開きます。 StgCreateStorageEx の場合、stgfmt パラメーターをSTGFMT_STORAGEに設定する必要があります。 StgOpenStorageEx の場合、stgfmt パラメーターを STGFMT_STORAGE または STGFMT_ANY に設定する必要があります。 どちらの場合も、 riid パラメーターを IID_IPropertySetStorage に設定する必要があります。 どちらの関数も、オブジェクト IPropertySetStorage インターフェイスへのポインターを提供します。 そのインターフェイスの Create メソッドまたは Open メソッドを呼び出すと、 IPropertyStorage インターフェイスへのポインターが取得されます。このポインターを使用して、任意のメソッドを呼び出すことができます。

IPropertySetStorage の複合ファイル実装へのポインターを取得する別の方法は、古い StgCreateDocfile 関数と StgOpenStorage 関数を呼び出すか、stgCreateStorageEx または StgOpenStorageEx 関数にIID_IStorageの riid パラメーターを指定することです。 どちらの場合も、オブジェクトの IStorage インターフェイスへのポインターが返されます。 永続プロパティ セットを使用して、IPropertySetStorage インターフェイスの QueryInterface を呼び出し、インターフェイス識別子 (IID) IID_IPropertySetStorageのヘッダー定義名を指定します。

使用するタイミング

IPropertyStorage を使用して、1 つのプロパティ セット内のプロパティを管理します。 そのメソッドは、プロパティ識別子に関連付けることができるプロパティと省略可能な文字列名の両方の読み取り、書き込み、および削除をサポートしています。 その他の方法では、標準のコミット操作と元に戻すストレージ操作がサポートされています。 また、プロパティ ストレージに関連付けられている時間を設定できるメソッドと、ユーザー インターフェイス コードなどの他のコードをプロパティ セットに関連付けるために使用できる CLSID の割り当てを許可するメソッドもあります。 Enum メソッドを呼び出すと、IEnumSTATPROPSTG の複合ファイル実装へのポインターが提供されます。これにより、セット内のプロパティを列挙できます。

Note

簡易モード プロパティ セット ストレージで StgCreateDocfile、StgCreateStorageEx、StgOpenStorage、または StgOpenStorageEx を呼び出して IPropertyStorage へのポインターを取得した場合、IPropertyStorage メソッドは単純モード ストリームの規則に従います。 プロパティ セット ストレージは、STGM_SIMPLE フラグを使用して作成または開かれたファイルに対して取得された場合、単純モードです。 この場合、基になるストリームを大きくすることは常に不可能であり、既存のプロパティを大きなプロパティに置き換えられません。 詳細については、「 IPropertySetStorage-Compound File Implementation」を参照してください。

 

IPropertyStorage とキャッシュ

IPropertyStorage の複合ファイル実装では、パフォーマンスを向上させるために、メモリ内のオープン プロパティ セットがキャッシュされます。 その結果、 Commit メソッドまたは Release (最後の参照) メソッドが呼び出されるまで、プロパティ セットへの変更は複合ファイルに書き込まれません。

Simple Mode プロパティ セット

プロパティ ストレージ オブジェクトは、単純モードのプロパティ セット ストレージ オブジェクトから作成される場合、単純モードです。 たとえば、プロパティ セットのストレージ オブジェクトは、 stgOpenStorageEx 関数から取得され、 grfMode パラメーターに STGM_SIMPLE フラグが設定されている場合、単純モードになります。 "簡易モード" は "単純なプロパティ セット" とは無関係であることに注意してください。 プロパティ セットは、grfFlags パラメーターに設定された PROPSETFLAG_NONSIMPLE フラグを使用して IPropertySetStorage::Create を呼び出すことによって作成される場合は簡単です。 単純なプロパティ セットと単純でないプロパティ セットの詳細については、「プロパティ セットの ストレージ オブジェクトとストリーム オブジェクト」を参照してください。

簡易モード のプロパティ ストレージ オブジェクトを作成する場合、その使用に制限はありません。 既存の単純モード プロパティ ストレージ オブジェクトを開くと、プロパティ セットを格納する基になるストリーム オブジェクトを拡張できません。 したがって、変更に大きなストリームが必要な場合は、このようなプロパティ ストレージ オブジェクトを常に変更できるわけではありません。

プロパティ セットの形式

IPropertyStorage の複合ファイル実装では、バージョン 0 とバージョン 1 の両方のプロパティ セットのシリアル化形式がサポートされています。 バージョン 1 の形式は、Windows 2000 で実行されているコンピューターでサポートされています。 詳細については、「 プロパティ セットのシリアル化」を参照してください。 プロパティ セットはバージョン 0 形式で作成され、新しい機能が要求されない限り、その形式のままです。 この場合、形式はバージョン 1 に更新されます。

たとえば、プロパティ セットが PROPSETFLAG_DEFAULT フラグを使用して作成された場合、その形式はバージョン 0 になります。 バージョン 0 の形式に準拠するプロパティの型が、そのプロパティ セットに書き込まれ、そのプロパティ セットから読み取られている限り、プロパティ セットはバージョン 0 形式のままです。 バージョン 1 のプロパティ型がプロパティ セットに書き込まれる場合、プロパティ セットはバージョン 1 に自動的に更新されます。 その後、バージョン 0 のみを認識する実装では、そのプロパティ セットを読み取ることができなくなりました。

IPropertyStorage 型とバリアント型

IPropertyStorage の複合ファイル実装では、PROPVARIANT 構造体の vt メンバーでVT_UNKNOWNまたはVT_DISPATCHバリアント型はサポートされていません。

次の表は、SafeArray 内でサポートされているバリアント型の一覧です。つまり、これらの値は PROPVARIANT 構造体の vt メンバー内のVT_ARRAYと組み合わせることができます。

IPropertyStorage の複合ファイル実装によって SafeArray 内でサポートされるバリアント型

VT_I1

VT_UI1

VT_I2

VT_UI2

VT_I4

VT_UI4

VT_INT

VT_UINT

VT_R4

VT_R8

VT_CY

VT_DATE

VT_BSTR

VT_BOOL

VT_DECIMAL

VT_ERROR

VT_VARIANT

 

 

VT_VARIANTをVT_ARRAYと組み合わせると、SafeArray 自体は PROPVARIANT 構造体を保持します。 ただし、これらの要素の型は、上記のリストから取得する必要があります。VT_VARIANTすることはできません。また、VT_VECTOR、VT_ARRAY、またはVT_BYREFインジケーターを含めることはできません。

IPropertyStorage メソッド

IPropertyStorage の複合ファイルの実装では、次のメソッドがサポートされています。

IPropertyStorage::ReadMultiple

rgpspec 配列で指定されたプロパティを読み取り、PROPVARIANT の rgvar 配列内のすべての有効なプロパティの値を指定します。 COM 複合ファイルの実装では、ストリームまたはストレージの種類を参照するプロパティ識別子が重複すると、IStorage::OpenStream または IStorage::OpenStorage の呼び出しが複数発生し、ReadMultiple の成功または失敗は、開始操作を共有する基になるストレージ実装の機能によって異なります。 複合ファイルではSTGM_SHARE_EXCLUSIVEが強制されるため、複数のオープン試行は失敗します。 同じ親ストレージから同じストレージ オブジェクトを複数回開く機能はサポートされていません。 STGM_SHARE_EXCLUSIVE フラグを指定する必要があります。

さらに、COM 複合ファイルの実装で同じ IPropertyStorage ポインターを使用して同じストリーム値またはストレージ値のプロパティが複数回要求された場合、スレッド セーフな操作を確保するために、プロパティが既に開かれているかどうか、および基になるファイル システムがストリームまたはストレージの複数の開口部を処理するかどうかに応じて、開く操作は成功または失敗します。 したがって、ストリーム値プロパティまたはストレージ値プロパティに対する ReadMultiple 操作では、常に IStorage::OpenStream、または IStorage::OpenStorage が呼び出されます。これにより、元のプロパティ セットが開かれたか作成されたときに指定されたアクセス (STGM_READWRITEなど) と共有フラグ (STGM_SHARE_EXCLUSIVE など) が渡されます。

メソッドが失敗した場合、 rgvar[] に書き込まれる値は未定義です。 ストリーム値またはストレージ値のプロパティが正常に開かれたが、実行が完了する前にエラーが発生した場合は、メソッドが返される前に解放する必要があります。

IPropertyStorage::WriteMultiple

rgpspec[] 配列で指定されたプロパティを書き込み、rgvar[] で指定された PROPVARIANT タグと値を割り当てます。 既に存在するプロパティには、指定された PROPVARIANT 値が割り当てられます。 現在存在しないプロパティが作成されます。

IPropertyStorage::D eleteMultiple

rgpspec[]で指定されたプロパティを削除します。

IPropertyStorage::ReadPropertyNames

rgpropid[] 配列で指定されたプロパティ ID に関連付けられている既存の文字列名を読み取ります。

IPropertyStorage::WritePropertyNames

rglpwstrName 配列で指定された文字列名を rgpropid 配列で指定されたプロパティ ID に割り当てます。

IPropertyStorage::D eletePropertyNames

rgpropid[] 配列で指定されたプロパティのプロパティ名を削除します。

IPropertyStorage::SetClass

プロパティ セット ストリームの CLSID を 設定します。 複合ファイルの実装では、非単純なプロパティ セットに CLSID を設定します ( IPropertySetStorage::Create で説明されているように、ストレージまたはストリーム値のプロパティを合法的に含めることができるもの)、基になるサブストレージに CLSID を設定して、 IStorage::Stat の呼び出しを通じて取得できるようにします。

IPropertyStorage::Commit

単純プロパティ セットと非単純プロパティ セットの両方について、プロパティ セットのメモリ イメージを基になるストレージにフラッシュします。 さらに、非simple transacted-mode プロパティ セットの場合、このメソッドは、プロパティ セットを含むストレージに対して ( IStorage::Commit のように) コミットを実行します。

IPropertyStorage::Revert

非シンプル プロパティ セットの場合のみ、基になるストレージの Revert メソッドを呼び出し、'contents' ストリームを再度開きます。 単純なプロパティ セットの場合、このインターフェイスは常にS_OKを返します。 非シンプル プロパティ セットは、 IPropertySetStorage::Create メソッドの PROPSETFLAG_NONSIMPLE フラグを使用して作成されたプロパティ セットです。 詳細については、「 プロパティ セットのストレージ オブジェクトとストリーム オブジェクト 」を参照してください。

IPropertyStorage::Enum

IEnumSTATPROPSTG のインスタンスを構築します。このメソッドを呼び出して、セット内の各プロパティに関する情報を提供する STATPROPSTG 構造体を列挙できます。 この実装では、プロパティ セット全体が読み取られ、 IEnumSTATPROPSTG::Clone が呼び出されたときに共有できる配列が作成されます。 プロパティ セットに対する変更は、開いている IEnumSTATPROPSTG インスタンスには反映されません。 このような変更を確認するには、この列挙子の新しいインスタンスを構築する必要があります。

IPropertyStorage::Stat

STATPROPSETSTG 構造体のメンバーを入力します。この構造体には、プロパティ セット全体に関するデータが含まれます。 戻り値として、 構造体へのポインターを提供します。 非シンプル ストレージ セットの場合、この実装では IStorage::Stat (または IStream::Stat) を呼び出して、基になるストレージまたはストリームから時刻を取得します。 単純なストレージ・セットの場合、時間は維持されません。

IPropertyStorage::SetTimes

非シンプル プロパティ セットの場合のみ、基になるストレージでサポートされる時間を設定します。 複合ファイル ストレージの実装では、変更、アクセス、作成の 3 つすべてがサポートされています。 SetTimes のこの実装では、基になるストレージの IStorage::SetElementTimes メソッドを呼び出して、これらの時刻を取得します。

IPropertyStorage

IStorage::SetElementTimes