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

オブジェクトの後続の開口部が読み取りまたは書き込みアクセスを拒否されないことを指定します。 共有グループのフラグが指定されていない場合、このフラグが想定されます。

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

最後にコミットされたバージョンへの排他アクセス権を持つストレージ オブジェクトを開きます。 したがって、優先度モードで開いている間は、他のユーザーはオブジェクトに変更をコミットできません。 コピー操作のパフォーマンス上の利点は得られますが、他のユーザーが変更をコミットできないようにします。 オブジェクトが優先度モードで開く時間を制限します。 優先度モード で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

0x000000000L

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

STGM_DIRECT

0x000000000L

ダイレクト モードでは、ストレージ要素またはストリーム要素に対する各変更が発生するたびに書き込まれることを示します。 これは、STGM_DIRECTもSTGM_TRANSACTEDも指定されていない場合の既定値です。

STGM_TRANSACTED

0x00010000L

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

STGM_NOSCRATCH

0x00100000L

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

STGM_NOSNAPSHOT

0x00200000L

このフラグは、STGM_SHARE_EXCLUSIVEまたはSTGM_SHARE_DENY_WRITEを使用せずに、STGM_TRANSACTEDでストレージ オブジェクトを開くときに使用されます。 この場合、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フラグを指定した場合、アクセス グループと共有グループから指定できるフラグの組み合わせは、次のいずれかです。

    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 モードで開かれたファイルのサイズに制限はありません。

Direct Single-Writer、Multiple-Reader モード

説明したように、そのオブジェクトがトランザクション モードで開かれている場合は、1 つのライターと 1 つのストレージ オブジェクトの複数のリーダーを持つことができます。 また、STGM_DIRECT_SWMR フラグを指定することで、ダイレクト モードでシングル ライターのマルチリーダー ケースを実現することもできます。

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

| STGM_DIRECT_SWMR | STGM_READWRITESTGM_SHARE_DENYWRITE

各リーダーは、次のフラグを使用して オブジェクトを開きます。

| STGM_DIRECT_SWMR | STGM_READSTGM_SHARE_DENY_NONE

このモードでは、ストレージ オブジェクトを変更するために、ライターは オブジェクトへの排他アクセス権を取得する必要があります。 これは、すべてのリーダーが閉じた場合に可能です。 ライターは IDirectWriterLock インターフェイスを使用して、この排他的アクセスを取得します。

シンプル モード

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

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

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

ストレージ オブジェクトが簡易モードで作成操作によって取得された場合:

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

ストレージ オブジェクトが単純モードで Open 操作によって取得された場合:

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

ストレージ要素が単純モードではないストレージ オブジェクトによって変更された場合、そのストレージ要素を単純モードで開くことはできません。

要件

関連項目

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx

StgOpenStorageOnILockBytes