IRootStorage
COM公式ドキュメント
IRootStorage インターフェイスは、ストレージオブジェクトを別の基になるファイルに切り替え、そのファイルにストレージオブジェクトを保存する単一のメソッドを含みます。
メソッド 1
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
SwitchToFile メソッドは、ストレージオブジェクトに関連付けられた現在のファイルを新しいファイルにコピーします。
| pszFile | LPWSTR | in | 新しいファイルのファイル名を指定する null 終端文字列へのポインター。既存のファイルの名前を指定することはできません。NULL の場合、このメソッドは一意の名前を持つ一時ファイルを作成します。 IStorage::Stat を呼び出すことで、一時ファイルの名前を取得できます。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| リターンコード | 説明 |
|---|---|
| S_OK | ファイルが正常にコピーされました。 |
| STG_E_MEDIUMFULL | ストレージデバイスの空き容量が不足しているため、ファイルはコピーされませんでした。 |
| STG_E_ACCESSDENIED | 呼び出し元がストレージデバイスにアクセスする権限を持っていないため、ファイルはコピーされませんでした。 |
| STG_E_INVALIDPOINTER | pszFile ポインターが有効でないため、ファイルはコピーされませんでした。 |
| STG_E_FILEALREADYEXISTS | 新しいファイル名 (pszFile) が既存のファイルを指しているため、ファイルはコピーされませんでした。 |
解説(Remarks)
IRootStorage::SwitchToFile メソッドは、ストレージオブジェクトに関連付けられたファイルをコピーします。COM コンテナーは、メモリ不足の状況でファイルのフルセーブを実行するために SwitchToFile を呼び出します。通常、これは、通常のフルセーブ操作 (すなわち、一時ファイルへの保存、元のファイルの削除、一時ファイルの名前変更) が E_OUTOFMEMORY エラーで失敗した後にのみ行われます。
ストレージオブジェクト、またはその中に含まれるものが別のプロセスにマーシャリングされている場合に SwitchToFile メソッドを呼び出すのは誤りです。 SwitchToFile を呼び出す前に、コンテナーは、ストレージオブジェクト内で読み込まれているか実行中のすべての要素に対して IPersistStorage::HandsOffStorage メソッドを呼び出す必要があります。HandsOffStorage メソッドは、要素にストレージポインターを解放させ、ハンズオフストレージモードに移行させます。また、コンテナーは、このルートストレージに含まれるストリームまたはストレージへのすべてのポインターも解放する必要があります。フルセーブ操作が完了した後、コンテナーは、含まれている要素を通常のストレージモードに戻します。
実装者への注意事項
独自のストレージオブジェクトを実装する場合、 IRootStorage のメソッド (QueryInterface、AddRef、Release を含む) は、追加のメモリやファイルハンドルを消費してはなりません。Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IRootStorage "{00000012-0000-0000-C000-000000000046}"
#usecom global IRootStorage IID_IRootStorage "{}"
#comfunc global IRootStorage_SwitchToFile 3 wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。