IStorage

IStorage インターフェースは、構造化ストレージオブジェクトの作成と管理をサポートします。

このストレージオブジェクトに含まれる、指定した名前のストリームオブジェクトを作成して開きます。

このメソッドは、次の値のいずれかを返すことがあります。

pwcsName パラメーターに指定した名前のストリームが既に存在し、grfMode パラメーターに STGM_CREATE フラグが含まれている場合、既存のストリームは新しく作成されたストリームに置き換えられます。古いストリームの破棄と新しいストリームオブジェクトの作成はいずれも、親ストレージオブジェクトのトランザクションモードの対象となります。

COM が提供する複合ファイル実装の IStorage::CreateStream メソッドは、次の動作をサポートしていません。

• STGM_DELETEONRELEASE フラグはサポートされていません。
• ストリームオブジェクトではトランザクションモード(STGM_TRANSACTED)はサポートされていません。
• 同じストレージから同じストリームを複数回開くことはサポートされていません。grfMode パラメーターには共有モードフラグ STGM_SHARE_EXCLUSIVE を指定する必要があります。

このストレージオブジェクト内の既存のストリームオブジェクトを、指定したアクセスモードで開きます。

このメソッドは、次の値のいずれかを返すことがあります。

IStorage::OpenStream は、このストレージオブジェクト内の既存のストリームオブジェクトを、grfMode で指定したアクセスモードで開きます。grfMode に指定できる権限には制限があります。たとえば、このストレージオブジェクトの権限は、そのストリームの権限を制限します。一般に、ストリームに対するアクセス制限は、その親ストレージに対する制限よりも厳しくする必要があります。複合ファイルのストリームは STGM_SHARE_EXCLUSIVE を指定して開く必要があります。

指定した名前で、指定したアクセスモードにより、このストレージオブジェクト内にネストされる新しいストレージオブジェクトを作成して開きます。

このメソッドは、次の値のいずれかを返すことがあります。

pwcsName パラメーターに指定した名前のストレージが親ストレージオブジェクト内に既に存在し、grfMode パラメーターに STGM_CREATE フラグが含まれている場合、既存のストレージは新しいストレージに置き換えられます。grfMode パラメーターに STGM_CONVERT フラグが含まれている場合、既存の要素は CONTENTS という名前のストリームオブジェクトに変換され、その CONTENTS ストリームオブジェクトを含む新しいストレージオブジェクトが作成されます。古い要素の破棄と新しいストレージオブジェクトの作成はいずれも、親ストレージオブジェクトのトランザクションモードの対象となります。STGM_CREATE を使用している場合は STGM_CONVERT を使用できない点に注意してください。

COM が提供する複合ファイル実装の IStorage::CreateStorage メソッドは、次の動作をサポートしていません。

• 非ルートストレージに対する STGM_PRIORITY フラグ。
• 同じ親ストレージから同じストレージオブジェクトを複数回開くこと。STGM_SHARE_EXCLUSIVE フラグを指定する必要があります。
• STGM_DELETEONRELEASE フラグ。このフラグを指定すると、関数は STG_E_INVALIDFLAG を返します。

指定した名前の既存のストレージオブジェクトを、指定したアクセスモードで開きます。

このメソッドは、次の値のいずれかを返すことがあります。

pstgPriority パラメーターが NULL の場合、無視されます。pstgPriority パラメーターが NULL でない場合、それはストレージオブジェクトの要素を以前に開いたもの(通常は優先モードで開いたもの)への IStorage ポインターです。そのストレージオブジェクトを閉じ、grfMode に従って再度開く必要があります。IStorage::OpenStorage メソッドが戻ると、pstgPriority は無効になります。ppstg パラメーターで提供された値を使用してください。

ストレージオブジェクトは STGM_DELETEONRELEASE を指定して開くことができます。その場合、オブジェクトは最後の解放(release)を受け取ったときに破棄されます。これは一時的なストレージオブジェクトの作成に役立ちます。

開いているストレージオブジェクトの内容全体を、別のストレージオブジェクトにコピーします。

このメソッドは、次の値のいずれかを返すことがあります。

このメソッドは、コピー元のストレージオブジェクトに含まれる要素を、コピー先に既に存在する要素とマージします。コピー先のストレージオブジェクトのレイアウトは、コピー元のストレージオブジェクトと異なる場合があります。

コピー処理は再帰的であり、コピー元の内部にネストされた要素に対して IStorage::CopyTo と IStream::CopyTo を呼び出します。

同じ名前の既存のストリームに上書きする形でストリームをコピーする場合、既存のストリームはまず削除され、その後コピー元のストリームに置き換えられます。同じ名前の既存のストレージに上書きする形でストレージをコピーする場合、既存のストレージは削除されません。そのため、コピー操作の後、コピー先の IStorage には、同じ名前の新しい要素で置き換えられなかった古い要素が残ります。

ストレージオブジェクトは、 IStorage 以外にも、 IRootStorage、 IPropertyStorage、 IPropertySetStorage などのインターフェースを公開する場合があります。rgiidExclude パラメーターを使用すると、これらの追加インターフェースの一部またはすべてをコピー操作から除外できます。

既存のサブストレージまたはストリームオブジェクトのより新しい、あるいはより効率的なコピーを持つ呼び出し元は、これらのオブジェクトの現在のバージョンをコピー操作から除外したい場合があります。snbExclude パラメーターと rgiidExclude パラメーターは、ストレージオブジェクトの既存のストレージまたはストリームを除外する 2 つの方法を提供します。

呼び出し元への注意

次のサンプルコードは、コピー元のストレージオブジェクトからコピー先のストレージオブジェクトへすべてをコピーする方法を示しています。

pstg->CopyTo(0, Null, Null, pstgDest)

MoveElementTo メソッドは、サブストレージまたはストリームを、このストレージオブジェクトから別のストレージオブジェクトへコピーまたは移動します。

このメソッドは、次の値のいずれかを返すことがあります。

IStorage::MoveElementTo メソッドは、通常、指定した要素に対して IStorage::CopyTo メソッドを呼び出してから、コピー元の要素を削除するのと同じです。この場合、 MoveElementTo メソッドは、移動を実行するためにコピー先のストレージオブジェクトの公開されている関数のみを使用します。

コピー元とコピー先のストレージオブジェクトが互いの実装について特別な知識を持っている場合(たとえば、同じ実装の異なるインスタンスである場合など)、このメソッドをより効率的に実装できます。

このメソッドを呼び出す前に、移動する要素を閉じ、コピー先のストレージを開いておく必要があります。また、コピー先のオブジェクトおよび要素を、移動元と同じストレージオブジェクト/要素名にすることはできません。つまり、要素を自分自身に移動することはできません。

Commit メソッドは、トランザクションモードで開いているストレージオブジェクトに対して行われた変更が、親ストレージに反映されるようにします。

このメソッドは、次の値のいずれかを返すことがあります。

IStorage::Commit は、トランザクションモードのストレージオブジェクトに対して変更を永続化します。トランザクションモードでは、変更はバッファーに蓄積され、このメソッドが呼び出されるまでストレージオブジェクトには反映されません。もう一方の方法は、オブジェクトをダイレクトモードで開くことで、この場合は変更がただちにストレージオブジェクトに反映されます。ダイレクトモードで開いたオブジェクトでは、ストレージオブジェクトへの変更を永続化するために IStorage::Commit を呼び出す必要はありません。ダイレクトモードで開いた非ルートストレージに対して IStorage::Commit メソッドを呼び出しても効果はありません。ルートストレージオブジェクトをダイレクトモードで開くと、メモリバッファー内の変更が基になるストレージデバイスに書き込まれることが保証されます。

コミット操作は、このストレージオブジェクトとその子における現在の変更を、ストレージ階層の 1 つ上のレベルに公開します。コミットする前に現在の変更を取り消すには、IStorage::Revert を呼び出して、最後にコミットされたバージョンにロールバックします。

IStorage::Commit を呼び出しても、このストレージオブジェクトの現在開いているネストされた要素には影響しません。それらは有効なまま使用できます。ただし、IStorage::Commit メソッドは、これらのネストされた要素への変更を自動的にはコミットしません。コミット操作は、既知の変更のみをストレージ階層の 1 つ上のレベルに公開します。したがって、ネストされたレベルへのトランザクションは、より上位のレベルにコミットする前に、このストレージオブジェクトにコミットする必要があります。

コミット操作では、コミット処理中にデータが保護されるように対策を講じる必要があります。

• ルートストレージオブジェクトへの変更をコミットする際、呼び出し元は戻り値を確認して操作が正常に完了したかどうかを判断し、完了していない場合は IStorage の古いコミット済みの内容がまだ無傷で復元可能であることを確認する必要があります。
• このストレージオブジェクトが一部の項目を除外して開かれていた場合、呼び出し元はコミットを呼び出す前にそれらを書き戻す責任があります。コミットを成功させるには、ストレージを開く際に書き込みモードが必要です。
• 同じストレージオブジェクトに対する複数の同時ライターを禁止しない限り、このメソッドを呼び出すアプリケーションは、あるライターが行った変更が別のライターの行った変更を誤って上書きしないように、grfCommitFlags パラメーターに少なくとも STGC_ONLYIFCURRENT を指定する必要があります。

Revert メソッドは、最後のコミット操作以降にストレージオブジェクトに対して行われたすべての変更を破棄します。

このメソッドは、次の値のいずれかを返すことがあります。

トランザクションモードで開かれたストレージオブジェクトに対して、IStorage::Revert メソッドは、このストレージオブジェクトへの未コミットの変更、またはネストされた要素からこのストレージオブジェクトにコミットされた変更を破棄します。

このメソッドが戻った後、復帰(revert)されたストレージオブジェクトから開かれていた既存の要素(サブストレージまたはストリーム)は無効になり、それ以降使用できなくなります。これらの復帰された要素を IUnknown::Release 以外の呼び出しで指定すると、エラー STG_E_REVERTED が返されます。

このメソッドは、ダイレクトモードで開かれたストレージオブジェクトには影響しません。

EnumElements メソッドは、このストレージオブジェクト内に含まれるストレージオブジェクトおよびストリームオブジェクトを列挙するために使用できる列挙子オブジェクトへのポインターを取得します。

このメソッドは、次の値のいずれかを返すことがあります。

このメソッドが返す列挙子オブジェクトは、 IEnumSTATSTG インターフェースを実装します。これは、Next、Reset、 Clone、Skip の各メソッドを含む標準の列挙子インターフェースの 1 つです。 IEnumSTATSTG は、 STATSTG 構造体の配列に格納されたデータを列挙します。

要素の列挙を可能にするには、ストレージオブジェクトを読み取りモードで開いておく必要があります。

列挙子オブジェクトは、要素を任意の順序で列挙してかまいません。 また、列挙子オブジェクトは、列挙をスナップショットとして扱うことも、 ストレージオブジェクトの現在の状態を列挙に反映させることもできます。

指定したストレージまたはストリームを、このストレージオブジェクトから削除します。

このメソッドは、次の値のいずれかを返すことがあります。

DestroyElement メソッドは、現在のストレージオブジェクトからサブストレージまたはストリームを削除します。 DestroyElement の呼び出しが成功すると、親ストレージから開かれていた、削除された要素のすべてのインスタンスが無効になります。

ストレージオブジェクトがトランザクションモードで開かれている場合、要素の破棄には、 DestroyElement の呼び出しに続いて IStorage::Commit を呼び出す必要があります。

RenameElement メソッドは、このストレージオブジェクト内の指定したサブストレージまたはストリームの名前を変更します。

このメソッドは、次の値のいずれかを返すことがあります。

IStorage::RenameElement は、このストレージオブジェクト内の指定したサブストレージまたはストリームの名前を変更します。ストレージオブジェクト内の要素は、開いている間は名前を変更できません。ストレージがトランザクションモードで開かれている場合、名前の変更操作は変更のコミットの対象となります。

IStorage::RenameElement メソッドは、トランザクションモードで開かれたストレージオブジェクトを使用する場合、メモリが少ない状況で動作する保証はありません。ダイレクトモードでは動作する場合があります。

SetElementTimes メソッドは、基になるファイルシステムがこのメソッドをサポートしている場合、指定したストレージ要素の更新時刻、アクセス時刻、作成時刻を設定します。

このメソッドは、次の値のいずれかを返すことがあります。

SetElementTimes は、このストレージオブジェクト内の指定したストレージ要素の時刻に関する統計情報を設定します。

すべてのファイルシステムがすべての時刻値をサポートしているわけではありません。このメソッドは、サポートされている時刻を設定し、それ以外は無視します。各時刻値パラメーターは NULL にすることができ、その場合は変更を行わないことを示します。

これらの時刻値を取得するには、 IStorage::Stat メソッドを呼び出します。

SetClass メソッドは、指定したクラス識別子(CLSID)をこのストレージオブジェクトに割り当てます。

このメソッドは、次の値のいずれかを返すことがあります。

ストレージオブジェクトは、最初に作成されたとき、関連付けられた CLSID として CLSID_NULL を持ちます。ストレージオブジェクトに CLSID を割り当てるには、SetClass を呼び出します。

ストレージオブジェクトの現在の CLSID を取得するには、 IStorage::Stat メソッドを呼び出します。

SetStateBits メソッドは、最大 32 ビットの状態情報をこのストレージオブジェクトに格納します。

このメソッドは、次の値のいずれかを返すことがあります。

状態ビットの値は現在定義されていません。

Stat メソッドは、この開いているストレージオブジェクトの STATSTG 構造体を取得します。

このメソッドは、次の値のいずれかを返すことがあります。

IStorage::Stat は、現在のストレージオブジェクトの STATSTG 構造体を取得します。 STATSTG 構造体には、ストレージオブジェクトに関する統計情報が含まれます。IStorage::EnumElements は、列挙子オブジェクトへのポインターを返します。このメソッドが返す列挙子オブジェクトは IEnumSTATSTG インターフェースを実装しており、これを通じて STATSTG 構造体の配列に格納されたデータが列挙されます。