StgOpenStorage 関数 (coml2api.h)

[アーティクル]
08/22/2023

StgOpenStorage 関数は、ファイルシステム内の既存のルートストレージオブジェクトを開きます。複合ファイルを開くには、この関数を使用します。ディレクトリ、ファイル、または概要カタログを開くために使用しないでください。入れ子になったストレージオブジェクトは、親の IStorage::OpenStorage メソッドを使用してのみ開くことができます。

メモアプリケーションでは、拡張および Windows 構造化ストレージ機能を利用するために、 StgOpenStorage ではなく新しい関数 StgOpenStorageEx を使用する必要があります。この関数 StgOpenStorage は、Windows 2000 で実行されているアプリケーションとの互換性を保つ目的で引き続き存在します。

構文

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

メモ他のユーザーに対する書き込みアクセス許可を拒否せずにストレージオブジェクトを読み取り/書き込みモードで開く (grfMode パラメーターでSTGM_SHARE_DENY_WRITEを指定する) 場合は、StgOpenStorage 呼び出しでストレージオブジェクト全体のスナップショットを行う必要があるため、時間のかかる操作になる可能性があります。

アプリケーションは、多くの場合、次のアクセス許可を持つストレージオブジェクトを開こうとします。アプリケーションが成功した場合、スナップショットコピーを作成する必要はありません。

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

メモアプリケーションは、スナップショットコピーを作成するコストを削減するために、ストレージオブジェクトを優先度モードで開くことができます (grfMode はSTGM_PRIORITYを指定します)。

snbExclude パラメーターは、ストレージオブジェクトを開く際に空にする、このストレージオブジェクト内の要素名のセットを指定します。ストリームの長さは 0 に設定されます。ストレージオブジェクトには、そのすべての要素が削除されています。特定のストリームを除外することで、スナップショットコピーを作成する費用を大幅に削減できます。ほとんどの場合、この方法は、最初にストレージオブジェクトを優先度モードで開き、次に現在除外されている要素を完全にメモリに読み取った後に使用されます。ストレージオブジェクトの以前の優先度モードの開始は 、pstgPriority パラメーターを介して渡して、優先度モードで暗黙的に除外を削除する必要があります。呼び出し元のアプリケーションは、コミットする前に、除外された項目の内容を書き換えます。したがって、この手法は、ドキュメントがアクティブな間にストレージオブジェクトへの一定のアクセスを必要としないアプリケーションにのみ役立つ可能性があります。

pstgPriority パラメーターは、呼び出し元が既存のストレージオブジェクト (多くの場合、優先度モードで開かれているもの) を、同じファイルで開いた新しいストレージオブジェクトと別のモードで置き換える便利な方法として使用します。 pstgPriority が NULL でない場合は、pwcsName ではなくファイル名を指定するために使用されます。これは無視されます。ただし、StgOpenStorage は状況によってはオブジェクトを解放し、他の状況では解放しないため、アプリケーションは常に pstgPriority に対して NULL を渡すことが推奨されます。特に、関数からエラーの結果が返された場合、呼び出し元はストレージオブジェクトが解放されたかどうかを判断できません。

pstgPriority パラメーターの機能は、次の例に示すように、呼び出し元によってより安全な方法で複製できます。

// Replacement for:
// HRESULT hr = StgOpenStorage(
//         NULL, pstgPriority, grfMode, NULL, 0, &amp;pstgNew);

STATSTG statstg;
HRESULT hr = pstgPriority-&gt;Stat(&amp;statstg, 0);
pStgPriority-&gt;Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
    hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &amp;pstgNew);
}

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	coml2api.h (Objbase.h を含む)
Library	Ole32.lib
[DLL]	Ole32.dll

こちらもご覧ください

IStorage

StgCreateDocfile

StgOpenStorageEx

StgOpenStorage 関数 (coml2api.h)

構文

パラメーター

戻り値

注釈

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース