STGM

STGM 定数は、オブジェクトの作成および削除の条件と、オブジェクトへのアクセスモードを示すフラグです。STGM 定数は、IStorage、IStream、IPropertySetStorage の各インターフェイスと、StgCreateDocfile、StgCreateStorageEx、StgCreateDocfileOnILockBytes、StgOpenStorage、StgOpenStorageEx の各関数で使用されます。

これらの要素は、OR 演算子で組み合わせて使用されることがよくあります。これらは次の表に示すグループ単位で解釈されます。1 つのグループから複数の要素を使用することはできません。

StgCreateStorageEx や IStorage::CreateStream などでオブジェクトを作成するときは、作成グループのフラグを使用します。

トランザクション処理の詳細については、「解説」セクションを参照してください。

STGM_READ

0x00000000L

オブジェクトが読み取り専用であること、つまり変更を加えられないことを示します。たとえば、ストリームオブジェクトを STGM_READ で開いた場合、ISequentialStream::Read メソッドは呼び出せますが、ISequentialStream::Write メソッドは呼び出せません。同様に、ストレージオブジェクトを STGM_READ で開いた場合、IStorage::OpenStream メソッドと IStorage::OpenStorage メソッドは呼び出せますが、IStorage::CreateStream メソッドと IStorage::CreateStorage メソッドは呼び出せません。

STGM_WRITE

0x00000001L

オブジェクトへの変更を保存できるようにしますが、そのデータへのアクセスは許可しません。提供されている IPropertyStorage および IPropertySetStorage インターフェイスの実装は、この書き込み専用モードをサポートしていません。

STGM_READWRITE

0x00000002L

オブジェクトのデータへのアクセスと変更を可能にします。たとえば、ストリームオブジェクトをこのモードで作成または開いた場合、IStream::Read と IStream::Write の両方を呼び出せます。この定数は、STGM_WRITE と STGM_READ の単純なビット単位の OR 演算ではないことに注意してください。

STGM_SHARE_DENY_NONE

0x00000040L

以降にオブジェクトを開く際に、読み取りアクセスも書き込みアクセスも拒否しないことを指定します。共有グループのフラグを 1 つも指定しない場合は、このフラグが指定されたものと見なされます。

STGM_SHARE_DENY_READ

0x00000030L

他のユーザーが以降にオブジェクトを STGM_READ モードで開くことを禁止します。通常はルートストレージオブジェクトに対して使用します。

STGM_SHARE_DENY_WRITE

0x00000020L

他のユーザーが以降にオブジェクトを STGM_WRITE または STGM_READWRITE アクセスで開くことを禁止します。トランザクションモードでは、STGM_SHARE_DENY_WRITE または STGM_SHARE_EXCLUSIVE による共有はスナップショットを必要としないため、パフォーマンスが大幅に向上します。トランザクション処理の詳細については、「解説」セクションを参照してください。

STGM_SHARE_EXCLUSIVE

0x00000010L

他のユーザーが以降にオブジェクトをどのモードでも開けないようにします。この値は、STGM_SHARE_DENY_READ と STGM_SHARE_DENY_WRITE の単純なビット単位の OR 演算ではないことに注意してください。トランザクションモードでは、STGM_SHARE_DENY_WRITE または STGM_SHARE_EXCLUSIVE による共有はスナップショットを必要としないため、パフォーマンスが大幅に向上します。トランザクション処理の詳細については、「解説」セクションを参照してください。

STGM_PRIORITY

0x00040000L

直近にコミットされたバージョンに対する排他アクセスでストレージオブジェクトを開きます。そのため、優先 (priority) モードで開いている間は、他のユーザーはそのオブジェクトへの変更をコミットできません。コピー操作のパフォーマンスは向上しますが、他のユーザーによるコミットを妨げることになります。優先モードでオブジェクトを開いたままにする時間は最小限にしてください。優先モードでは STGM_DIRECT と STGM_READ を指定する必要があり、STGM_DELETEONRELEASE は指定できません。STGM_DELETEONRELEASE は、StgCreateStorageEx などでルートオブジェクトを作成する場合にのみ有効です。StgOpenStorageEx などで既存のルートオブジェクトを開く場合には無効です。また、IStorage::OpenStorage などでサブ要素を作成または開く場合にも無効です。

STGM_CREATE

0x00001000L

新しいオブジェクトで置き換える前に、既存のストレージオブジェクトまたはストリームを削除することを示します。このフラグを指定した場合、既存のオブジェクトの削除に成功したときにのみ新しいオブジェクトが作成されます。

このフラグは、次のものを作成しようとするときに使用します。

• ディスク上にストレージオブジェクトを作成しようとしたが、同じ名前のファイルが存在する場合。
• ストレージオブジェクト内にオブジェクトを作成しようとしたが、指定した名前のオブジェクトが存在する場合。
• バイト配列オブジェクトを作成しようとしたが、指定した名前のものが存在する場合。

このフラグは、StgOpenStorageEx や IStorage::OpenStream などの開く操作では使用できません。

STGM_CONVERT

0x00020000L

"Contents" という名前のストリームに既存のデータを保持したまま、新しいオブジェクトを作成します。ストレージオブジェクトまたはバイト配列の場合、既存のファイルまたはバイト配列が階層化されたストレージオブジェクトを現在含んでいるかどうかにかかわらず、古いデータはストリームとして整形されます。このフラグは、ルートストレージオブジェクトを作成するときにのみ使用できます。ストレージオブジェクト内では使用できません。たとえば、IStorage::CreateStream では使用できません。また、このフラグと STGM_DELETEONRELEASE フラグを同時に使用することもできません。

STGM_FAILIFTHERE

0x00000000L

指定した名前のオブジェクトが既に存在する場合、作成操作を失敗させます。この場合、STG_E_FILEALREADYEXISTS が返されます。これは既定の作成モードです。つまり、他の作成フラグを指定しない場合は、STGM_FAILIFTHERE が指定されたものと見なされます。

STGM_DIRECT

0x00000000L

直接 (direct) モードでは、ストレージ要素またはストリーム要素への変更が発生するたびに書き込まれることを示します。STGM_DIRECT と STGM_TRANSACTED のどちらも指定しない場合は、これが既定になります。

STGM_TRANSACTED

0x00010000L

トランザクションモードでは、変更がバッファーに蓄積され、明示的なコミット操作が呼び出された場合にのみ書き込まれることを示します。変更を破棄するには、IStream、IStorage、または IPropertyStorage インターフェイスの Revert メソッドを呼び出します。COM 複合ファイルによる IStorage の実装は、トランザクション処理されたストリームをサポートしていません。つまり、ストリームは直接モードでのみ開くことができ、その変更を元に戻すことはできませんが、トランザクション処理されたストレージはサポートされます。同様に、IPropertySetStorage の複合ファイル実装、スタンドアロン実装、および NTFS ファイルシステム実装も、トランザクション処理された単純なプロパティセットをサポートしていません。これらのプロパティセットはストリームに格納されるためです。ただし、IPropertySetStorage::Create の grfFlags パラメーターに PROPSETFLAG_NONSIMPLE フラグを指定することで作成できる非単純プロパティセットのトランザクション処理はサポートされます。

STGM_NOSCRATCH

0x00100000L

トランザクションモードでは通常、Commit メソッドが呼び出されるまで変更を保存するために一時的なスクラッチファイルが使用されることを示します。STGM_NOSCRATCH を指定すると、そのために新しいファイルを作成する代わりに、元のファイルの未使用部分を作業領域として使用できます。これは元のファイル内のデータには影響せず、場合によってはパフォーマンスの向上につながります。このフラグを STGM_TRANSACTED と併せて指定せずに使用することはできません。また、このフラグはルートを開くときにのみ使用できます。NoScratch モードの詳細については、「解説」セクションを参照してください。

STGM_NOSNAPSHOT

0x00200000L

このフラグは、ストレージオブジェクトを STGM_TRANSACTED を指定し、かつ STGM_SHARE_EXCLUSIVE または STGM_SHARE_DENY_WRITE を指定せずに開くときに使用します。この場合、STGM_NOSNAPSHOT を指定すると、システム提供の実装がファイルのスナップショットコピーを作成しなくなります。代わりに、ファイルへの変更はファイルの末尾に書き込まれます。コミット時に統合が実行され、かつそのファイルへの書き込み側が 1 つだけである場合を除き、未使用領域は回収されません。ファイルをスナップショットなしモードで開いている場合、STGM_NOSNAPSHOT を指定せずに別の開く操作を実行することはできません。このフラグは、ルートを開く操作でのみ使用できます。NoSnapshot モードの詳細については、「解説」セクションを参照してください。

STGM_SIMPLE

0x08000000L

限定的ではあるものの頻繁に使用されるケースにおいて、複合ファイルのより高速な実装を提供します。詳細については、「解説」セクションを参照してください。

STGM_DIRECT_SWMR

0x00400000L

シングルライター/マルチリーダーのファイル操作を直接モードでサポートします。詳細については、「解説」セクションを参照してください。

STGM_DELETEONRELEASE

0x04000000L

ルートストレージオブジェクトが解放されたときに、基になるファイルを自動的に破棄することを示します。この機能は一時ファイルの作成に特に便利です。このフラグは、StgCreateStorageEx などでルートオブジェクトを作成するときにのみ使用できます。StgOpenStorageEx などでルートオブジェクトを開くときや、IStorage::CreateStream などでサブ要素を作成または開くときには無効です。また、このフラグと STGM_CONVERT フラグを同時に使用することもできません。

これらのフラグは組み合わせて使用できますが、関連するフラグの各グループから選択できるのは 1 つだけです。通常、これらの定数を使用するすべての関数およびメソッドでは、アクセスグループと共有グループからそれぞれ 1 つのフラグを指定する必要があります。他のグループのフラグは省略可能です。

トランザクションモード

STGM_DIRECT フラグを指定する場合、アクセスグループと共有グループから指定できるのは、次の組み合わせのいずれか 1 つだけです。

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

STGM_TRANSACTED を指定しない場合は直接モードが暗黙的に適用されることに注意してください。つまり、STGM_DIRECT と STGM_TRANSACTED のどちらも指定しない場合は、STGM_DIRECT が指定されたものと見なされます。

STGM_TRANSACTED フラグを指定すると、オブジェクトはトランザクションモードで作成または開かれます。このモードでは、オブジェクトへの変更はコミットされるまで保持されません。たとえば、トランザクション処理されたストレージオブジェクトへの変更は、IStorage::Commit メソッドが呼び出されるまで永続化されません。Commit メソッドを呼び出す前にストレージオブジェクトが解放された場合 (最終解放)、または IStorage::Revert メソッドが呼び出された場合、そのストレージオブジェクトへの変更は失われます。

オブジェクトをトランザクションモードで作成または開いた場合、実装は必要に応じて更新を取り消せるように、元のデータと更新内容の両方を保持しなければなりません。これは通常、コミットされるまで変更をスクラッチ領域に書き込むか、直近にコミットされたデータのコピー (スナップショット) を作成することによって実現されます。

ルートストレージオブジェクトをトランザクションモードで開く場合、STGM_NOSCRATCH フラグと STGM_NOSNAPSHOT フラグによって、スクラッチデータとスナップショットコピーの配置場所と動作を制御し、パフォーマンスを最適化できます。(ルートストレージオブジェクトは、たとえば StgOpenStorageEx 関数から取得されます。IStorage::OpenStorage メソッドから取得されるストレージオブジェクトはサブストレージオブジェクトです。) 通常、スクラッチデータとスナップショットは、ストレージとは別の一時ファイルに格納されます。

これらのフラグの効果は、ルートストレージにアクセスする読み取り側および書き込み側の数によって異なります。

「シングルライター」のケースでは、トランザクションモードのストレージオブジェクトが書き込みアクセスで開かれ、そのファイルへの他のアクセスは存在しません。つまり、ファイルは STGM_TRANSACTED、STGM_WRITE または STGM_READWRITE のアクセス、および STGM_SHARE_EXCLUSIVE の共有で開かれます。この場合、ストレージオブジェクトへの変更はスクラッチ領域に書き込まれます。それらの変更がコミットされると、元のストレージにコピーされます。したがって、ストレージオブジェクトに実際の変更が加えられていなければ、不要なデータ転送は発生しません。

「マルチライター」のケースでは、トランザクション処理されたストレージオブジェクトが書き込みアクセスで開かれますが、他の書き込み側を許可する形で共有されます。つまり、ストレージオブジェクトは STGM_TRANSACTED、STGM_WRITE または STGM_READWRITE のアクセス、および STGM_SHARE_DENY_READ の共有で開かれます。代わりに STGM_SHARE_DENY_NONE の共有を指定した場合は、「マルチライター、マルチリーダー」のケースになります。これらのケースでは、開く操作の際に元のデータのスナップショットが作成されます。そのため、ストレージに実際の変更が加えられなくても、また実際に別の書き込み側が同時に開かなくても、開く際にデータ転送が必要になります。その結果、ストレージオブジェクトを STGM_SHARE_DENY_WRITE モードまたは STGM_SHARE_EXCLUSIVE モードで開くと、オープン時の最良のパフォーマンスが得られます。複数の書き込み側が存在する場合に変更がどのようにコミットされるかの詳細については、IStorage::Commit を参照してください。

「シングルライター、マルチリーダー」のケースでは、トランザクション処理されたストレージオブジェクトが書き込みアクセスで開かれますが、読み取り側と共有されます。つまり、書き込み側はストレージオブジェクトを STGM_TRANSACTED、STGM_READWRITE または STGM_WRITE のアクセス、および STGM_SHARE_DENY_WRITE の共有で開きます。読み取り側はストレージを STGM_TRANSACTED、STGM_READ のアクセス、および STGM_SHARE_DENY_NONE の共有で開きます。この場合、書き込み側は未コミットの変更を格納するためにスクラッチ領域を使用します。上記のケースと同様に、読み取り側はデータのスナップショットコピーが作成される間、オープン時のパフォーマンス低下を被ります。

通常、スクラッチ領域は元のデータとは別の一時ファイルです。変更が元のファイルにコミットされる際には、その一時ファイルからデータを転送しなければなりません。このデータ転送を回避するには、STGM_NOSCRATCH フラグを指定します。このフラグを指定すると、別個の一時ファイルではなく、ストレージオブジェクトファイルの一部がスクラッチ領域として使用されます。その結果、必要なデータ転送がわずかで済むため、変更のコミットを高速に実行できます。欠点として、元のデータとスクラッチ領域の両方を収められる大きさまで拡張する必要があるため、ストレージファイルが本来よりも大きくなる可能性があります。データを統合してこの不要な領域を削除するには、STGM_NOSCRATCH フラグを設定せずに、ルートストレージをトランザクションモードで開き直します。その後、STGC_CONSOLIDATE フラグを設定して IStorage::Commit を呼び出します。

スナップショット領域も、スクラッチ領域と同様に通常は一時ファイルであり、これも STGM フラグで制御できます。STGM_NOSNAPSHOT フラグを指定すると、別個の一時スナップショットファイルは作成されません。代わりに、オブジェクトごとに 1 つ以上の書き込み側が存在する場合でも、元のデータが変更されることはありません。変更がコミットされるとファイルに追加されますが、元のデータはそのまま残ります。このモードは、開く操作の際にスナップショットを作成する必要がなくなり実行時間が短縮されるため、効率が向上します。ただし、ファイル内のデータが上書きされることは決してないため、このモードを使用するとストレージファイルが非常に大きくなる可能性があります。NoSnapshot モードで開いたファイルのサイズに制限はありません。

直接モードでのシングルライター/マルチリーダー

前述のとおり、ストレージオブジェクトをトランザクションモードで開けば、1 つの書き込み側と複数の読み取り側を持つことができます。STGM_DIRECT_SWMR フラグを指定すれば、直接モードでもシングルライター/マルチリーダーを実現できます。

STGM_DIRECT_SWMR モードでは、ある呼び出し元がオブジェクトを読み取り/書き込みアクセスで開いている間に、他の呼び出し元が同時にそのファイルを読み取り専用アクセスで開くことができます。このフラグを STGM_TRANSACTED フラグと組み合わせて使用することはできません。このモードでは、書き込み側は次のフラグでオブジェクトを開きます。

STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENYWRITE

また、各読み取り側は次のフラグでオブジェクトを開きます。

STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

このモードでストレージオブジェクトを変更するには、書き込み側がそのオブジェクトへの排他アクセスを取得する必要があります。これは、すべての読み取り側がオブジェクトを閉じた時点で可能になります。書き込み側は、この排他アクセスを取得するために IDirectWriterLock インターフェイスを使用します。

簡易モード

簡易モード (STGM_SIMPLE) は、完全な保存操作を実行するアプリケーションに適しています。効率的ですが、次の制約があります。

• サブストレージはサポートされません。
• ストレージオブジェクト、およびそこから取得したストリームオブジェクトはマーシャリングできません。
• 各ストリームには最小サイズがあります。ストリームの解放時に書き込まれたバイト数が最小サイズに満たない場合、そのストリームは最小サイズまで拡張されます。たとえば、ある IStream 実装の最小サイズが 4 KB であるとします。ストリームを作成して 1 KB を書き込むと、その IStream の最終解放時にストリームサイズは自動的に 4 KB まで拡張されます。その後、そのストリームを開いて IStream::Stat メソッドを呼び出すと、サイズは 4 KB と表示されます。
• IStorage や IStream のすべてのメソッドが実装でサポートされるわけではありません。詳細については、IStorage - Compound File Implementation および IStream - Compound File Implementation を参照してください。

マーシャリングとは、リモートプロシージャコール (RPC) 内で、インターフェイスメソッドのパラメーターをスレッド境界またはプロセス境界を越えて送信するために、パッケージ化および展開する処理のことです。詳細については、Marshaling Details および Interface Marshaling を参照してください。

簡易モードで作成 (Create) 操作によってストレージオブジェクトを取得した場合は、次のようになります。

• ストリーム要素を作成できますが、開くことはできません。
• IStorage::CreateStream を呼び出してストリーム要素を作成した場合、そのストリームオブジェクトを解放するまで別のストリームを作成することはできません。
• すべてのストリームを書き込んだ後、IStorage::Commit を呼び出して変更をフラッシュします。

簡易モードで開く (Open) 操作によってストレージオブジェクトを取得した場合は、次のようになります。

• 一度に 1 つのストリーム要素しか開くことができません。
• IStream::SetSize メソッドの呼び出しや、ストリームの末尾を超えたシークまたは書き込みによって、ストリームのサイズを変更することはできません。ただし、すべてのストリームには最小サイズがあるため、元々書き込まれたデータがそれより少なくても、そのサイズまでストリームを使用できます。ストリームのサイズを調べるには、IStream::Stat メソッドを使用します。

簡易モードではないストレージオブジェクトによってストレージ要素が変更された場合、その要素を再び簡易モードで開くことはできなくなるので注意してください。