StgOpenStorage 関数 (coml2api.h)
StgOpenStorage 関数は、ファイル システム内の既存のルート ストレージ オブジェクトを開きます。 複合ファイルを開くには、この関数を使用します。 ディレクトリ、ファイル、または概要カタログを開くために使用しないでください。 入れ子になったストレージ オブジェクトは、親 の IStorage::OpenStorage メソッドを使用してのみ開くことができます。
構文
HRESULT StgOpenStorage(
[in] const WCHAR *pwcsName,
[in] IStorage *pstgPriority,
[in] DWORD grfMode,
[in] SNB snbExclude,
[in] DWORD reserved,
[out] IStorage **ppstgOpen
);
パラメーター
[in] pwcsName
開くストレージ オブジェクトを含む null で終わる Unicode 文字列ファイルのパスへのポインター。 pstgPriority パラメーターが NULL でない場合、このパラメーターは無視されます。
[in] pstgPriority
NULL にする必要がある IStorage インターフェイスへのポインター。 NULL でない場合、このパラメーターは「解説」セクションで後述するように使用されます。
StgOpenStorage が戻った後、pStgPriority で指定されたストレージ オブジェクトが解放されている可能性があるため、使用しないでください。
[in] grfMode
ストレージ オブジェクトを開くために使用するアクセス モードを指定します。
[in] snbExclude
NULL でない場合は、ストレージ オブジェクトが開かれる際に除外されるストレージ内の要素のブロックへのポインター。 除外は、スナップショットコピーが開いている状態で行われるかどうかに関係なく発生します。 NULL を指定できます。
[in] reserved
将来使用するために予約済みであることを示します。は 0 である必要があります。
[out] ppstgOpen
開いているストレージへのインターフェイス ポインターを受け取る IStorage* ポインター変数へのポインター。
戻り値
StgOpenStorage 関数は、HRESULT でラップされたファイル システム エラーやシステム エラーを返すこともできます。 詳細については、「 エラー処理戦略 」および「 不明なエラーの処理」を参照してください。
注釈
StgOpenStorage 関数は、grfMode パラメーターのアクセス モードに従って指定されたルート ストレージ オブジェクトを開き、成功した場合は、ppstgOpen パラメーターで開いているストレージ オブジェクトへの IStorage ポインターを提供します。
サブストレージのないストレージ オブジェクトを保存するための単純モードをサポートするために、 StgOpenStorage 関数は grfMode パラメーターで有効なモードとして次の 2 つのフラグの組み合わせのいずれかを受け入れます。
STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE
STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE
シングル ライター、マルチリーダー、ダイレクト モードをサポートするために、最初のフラグの組み合わせはライターの有効な grfMode パラメーターです。 2 番目のフラグの組み合わせは、リーダーに対して有効です。
STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE
STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE
ダイレクト モードでは、次の 3 つの組み合わせのいずれかが有効です。
STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE
STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE
STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE
STGM_READWRITE | STGM_SHARE_DENY_WRITE
// transacted versus direct mode omitted for exposition
以前のアクセス許可が失敗した場合、アプリケーションはアクセス許可の使用に戻り、スナップショットコピーを作成できます。 アプリケーションでは、時間のかかるコピーを作成する前に、ユーザーにメッセージを表示する必要があります。
STGM_READWRITE
// transacted versus direct mode omitted for exposition
アクセス モードによって暗黙的に示されるドキュメント共有セマンティクスが適切な場合、アプリケーションは次のようにストレージを開こうとします。 この場合、アプリケーションが成功した場合、スナップショットコピーは作成されません (STGM_SHARE_DENY_WRITEが指定されたため、他のユーザーの書き込みアクセスを拒否するため)。
STGM_READ | STGM_SHARE_DENY_WRITE
// transacted versus direct mode omitted for exposition
pstgPriority パラメーターは、呼び出し元が既存のストレージ オブジェクト (多くの場合、優先度モードで開かれているもの) を、同じファイルで開いた新しいストレージ オブジェクトと別のモードで置き換える便利な方法として使用します。 pstgPriority が NULL でない場合は、pwcsName ではなくファイル名を指定するために使用されます。これは無視されます。 ただし、StgOpenStorage は状況によってはオブジェクトを解放し、他の状況では解放しないため、アプリケーションは常に pstgPriority に対して NULL を渡すことが推奨されます。 特に、関数からエラーの結果が返された場合、呼び出し元はストレージ オブジェクトが解放されたかどうかを判断できません。
pstgPriority パラメーターの機能は、次の例に示すように、呼び出し元によってより安全な方法で複製できます。
// Replacement for:
// HRESULT hr = StgOpenStorage(
// NULL, pstgPriority, grfMode, NULL, 0, &pstgNew);
STATSTG statstg;
HRESULT hr = pstgPriority->Stat(&statstg, 0);
pStgPriority->Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &pstgNew);
}
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | coml2api.h (Objbase.h を含む) |
| Library | Ole32.lib |
| [DLL] | Ole32.dll |