StgOpenStorageOnILockBytes 関数 (coml2api.h)

StgOpenStorageOnILockBytes 関数は、ディスク ファイルに存在しない既存のストレージ オブジェクトを開きますが、代わりに、呼び出し元によって提供される基になるバイト配列を持ちます。

構文

HRESULT StgOpenStorageOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  IStorage   *pstgPriority,
  [in]  DWORD      grfMode,
  [in]  SNB        snbExclude,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

パラメーター

[in] plkbyt

開くストレージ オブジェクトを含む基になるバイト配列オブジェクトへの ILockBytes ポインター。

[in] pstgPriority

NULL にする必要がある IStorage インターフェイスへのポインター。 NULL でない場合、このパラメーターは「解説」セクションで後述するように使用されます。

StgOpenStorageOnILockBytes が返された後、pStgPriority で指定されたストレージ オブジェクトが解放されている可能性があり、使用しなくなります。

[in] grfMode

ストレージ オブジェクトを開くために使用するアクセス モードを指定します。 詳細については、 STGM 定数 と以下の「解説」セクションを参照してください。

[in] snbExclude

NULL を指定できます。 NULL でない場合、このパラメーターは、ストレージ オブジェクトが開かれる際に除外される、このストレージ内の要素のブロックを指します。 この除外は、スナップショットコピーが開いている状態で行われるかどうかとは無関係に発生します。

[in] reserved

将来使用するために予約済みであることを示します。は 0 である必要があります。

[out] ppstgOpen

正常に戻ったら、開いているストレージへの IStorage ポインターの場所を指します。

戻り値

StgOpenStorageOnILockBytes 関数は、ファイル システム エラー、または HRESULT でラップされたシステム エラー、または ILockBytes インターフェイス エラーの戻り値を返すこともできます。 「エラー処理戦略」と「不明なエラーの処理」を参照してください。

注釈

StgOpenStorageOnILockBytes によって 、指定されたルート ストレージ オブジェクトが開きます。 開いているストレージ オブジェクトの IStorage インターフェイスへのポインターは、 ppstgOpen パラメーターを使用して指定されます。

ストレージ オブジェクトは、 StgCreateDocfileOnILockBytes 関数によって以前に作成されている必要があります。

プログラマ指定のバイト配列オブジェクトを指定する場合を除き、 StgOpenStorageOnILockBytes は StgOpenStorage 関数に似ています。 ストレージ オブジェクトは、 grfMode パラメーターのアクセス モードに従って開かれます。これには、次の制限があります。

共有モードの動作とトランザクションの分離は、LOCK_ONLYONCEセマンティクスを使用して LockRegion と UnlockRegion をサポートする ILockBytes 実装によって異なります。 実装では、STATSTG の grfLocksSupported メンバーにLOCK_ONLYONCE ビットを設定することで、この機能をサポートする構造化ストレージを示すことができます。 ILockBytes 実装でこの機能がサポートされていない場合、共有モードは適用されず、ルート レベルのトランザクション コミットは、同じバイト配列で開かれた他のトランザクション インスタンスと正しく連携しません。 CreateStreamOnHGlobal 実装など、領域ロックをサポートしない ILockBytes 実装を使用するアプリケーションでは、同じバイト配列で複数の同時実行インスタンスを開かないようにする必要があります。

StgOpenStorageOnILockBytes では、単純モードはサポートされていません。 STGM_SIMPLE フラグが存在する場合は無視されます。

pStgPriority パラメーターは、呼び出し元が既存のストレージ オブジェクト (多くの場合、優先度モードで開かれているもの) を同じバイト配列で開いた新しいストレージ オブジェクトに置き換える際の利便性を目的としています。 StgOpenStorage の pStgPriority パラメーターとは異なり、このパラメーターは StgOpenStorageOnILockBytes によって実行されるオープン操作には影響せず、呼び出し元が解放する既存のストレージ オブジェクトです。 StgOpenStorageOnILockBytes は状況によってはオブジェクトを解放し、他の状況では解放しないため、呼び出し元はこのパラメーターに対して常に NULL を渡す必要があります。 次の例に示すように、 pStgPriority パラメーターの使用は、 StgOpenStorageOnILockBytes を呼び出す前にオブジェクトを解放することで、呼び出し元によってより安全な方法で複製できます。

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);

pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);
    

詳細については、「 StgOpenStorage」を参照してください。

要件

こちらもご覧ください

StgCreateDocfileOnILockBytes

StgOpenStorage