次の方法で共有

STGM 定数

STGM 定数は、オブジェクトおよびオブジェクトのアクセス・モードを作成および削除するための条件を示すフラグです。 STGM 定数は、 IStorage、 IStream、 IPropertySetStorage インターフェイス、および StgCreateDocfile、 StgCreateStorageEx、 StgCreateDocfileOnILockBytes、 StgOpenStorage、および StgOpenStorageEx 関数 に 含まれています。

多くの場合、これらの要素は OR演算子を使用して結合されます。 これらは、次の表に示すようにグループで解釈されます。 1 つのグループから複数の要素を使用することはできません。

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

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

グループ フラグ 価値
アクセス STGM_READ 0x000000000L
STGM_WRITE 0x00000001L
STGM_READWRITE 0x00000002L
共有 STGM_SHARE_DENY_NONE 0x00000040L
STGM_SHARE_DENY_READ 0x00000030L
STGM_SHARE_DENY_WRITE 0x00000020L
STGM_SHARE_EXCLUSIVE 0x00000010L
STGM_PRIORITY 0x00040000L
創造 STGM_CREATE 0x00001000L
STGM_CONVERT 0x00020000L
STGM_FAILIFTHERE 0x000000000L
トランザクション STGM_DIRECT 0x000000000L
STGM_TRANSACTED 0x00010000L
トランザクションのパフォーマンス STGM_NOSCRATCH 0x00100000L
STGM_NOSNAPSHOT 0x00200000L
ダイレクト SWMR とシンプル STGM_SIMPLE 0x08000000L
STGM_DIRECT_SWMR 0x00400000L
リリース時の削除 STGM_DELETEONRELEASE 0x04000000L

STGM_READ

0x000000000L

オブジェクトが読み取り専用であることを示します。つまり、変更を行うことはできません。 たとえば、ストリーム オブジェクトが 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 モードで開くファイルのサイズに制限はありません。

ダイレクト シングル ライター、Multiple-Reader モード

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

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

STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENYWRITE

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

STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

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

単純モード

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

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

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

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

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

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

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

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

要求事項

要件 価値
サポートされている最小のクライアント
 Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー
 Windows 2000 Server [デスクトップ アプリのみ]
ヘッダ
ObjBase.h

こちらも参照ください

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageExの

StgOpenStorage

StgOpenStorageExの

StgOpenStorageOnILockBytes