StgOpenStorageEx 関数 (coml2api.h)

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

StgOpenStorageEx 関数は、ファイルシステム内の既存のルートストレージオブジェクトを開きます。複合ファイルと通常のファイルを開くには、この関数を使用します。新しいファイルを作成するには、 StgCreateStorageEx 関数を使用します。

メモ拡張機能を使用するには、 StgOpenStorage ではなく、すべての Windows 2000、Windows XP、および Windows Server 2003 アプリケーションで StgOpenStorageEx を呼び出す必要があります。 StgOpenStorage 関数は、Windows 2000 以前のアプリケーションとの互換性のために使用されます。

構文

HRESULT StgOpenStorageEx(
  [in]      const WCHAR          *pwcsName,
  [in]      DWORD                grfMode,
  [in]      DWORD                stgfmt,
  [in]      DWORD                grfAttrs,
  [in, out] STGOPTIONS           *pStgOptions,
  [in]      PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]      REFIID               riid,
  [out]     void                 **ppObjectOpen
);

パラメーター

[in] pwcsName

ストレージオブジェクトを含む null で終わる Unicode 文字列ファイルのパスへのポインター。この文字列サイズは 、MAX_PATH 文字を超えることはできません。

Windows Server 2003 および Windows XP/2000: CreateFile 関数とは異なり、"\?" プレフィックスを使用してMAX_PATHの制限を超えることはできません。

[in] grfMode

新しいストレージオブジェクトを開くアクセスモードを示す値。詳細については、「 STGM 定数」を参照してください。呼び出し元が STGM_CREATE または STGM_CONVERTと共にトランザクションモードを指定した場合、ルートストレージに対してコミット操作が呼び出されたときに上書きまたは変換が発生します。ルートストレージオブジェクトに対して IStorage::Commit が呼び出されない場合、ファイルの以前の内容が復元されます。 STGM_CREATEとSTGM_CONVERTをSTGM_NOSNAPSHOT フラグと組み合わせることはできません。これは、ファイルがトランザクションモードで上書きまたは変換されるときにスナップショットコピーが必要であるためです。

STGM_WRITEまたはSTGM_READWRITEにアクセスできるダイレクトモード (STGM_DIRECT) でストレージオブジェクトを開く場合は、STGM_DIRECT_SWMR モードが指定されていない限り、共有モードをSTGM_SHARE_EXCLUSIVEする必要があります。詳細については、「解説」を参照してください。 STGM_READにアクセスできるダイレクトモードでストレージオブジェクトを開く場合、STGM_PRIORITYまたはSTGM_DIRECT_SWMRが指定されていない限り、共有モードはSTGM_SHARE_EXCLUSIVEまたはSTGM_SHARE_DENY_WRITEである必要があります。詳細については、「解説」を参照してください。

ファイルを開くモードは、実装のパフォーマンスに影響を与える可能性があります。詳細については、「複合ファイルの実装の制限」を参照してください。

[in] stgfmt

ストレージファイルの形式を示す値。詳細については、 STGFMT 列挙を参照してください。

[in] grfAttrs

stgfmt パラメーターの値に依存する値。

STGFMT_DOCFILE はゼロ (0) または FILE_FLAG_NO_BUFFERINGにする必要があります。この値の詳細については、「 CreateFile」を参照してください。 pStgOptions で指定されたファイルのセクターサイズが、基になるディスクの物理セクターサイズの整数倍数でない場合、この操作は失敗します。 stgfmt の他のすべての値は 0 である必要があります。

[in, out] pStgOptions

開かれたストレージオブジェクトに関するデータを含む STGOPTIONS 構造体へのポインター。 pStgOptions パラメーターは、stgfmt パラメーターが STGFMT_DOCFILE に設定されている場合にのみ有効です。 stgOpenStorageEx を呼び出す前に、usVersion メンバーを設定する必要があります。詳細については、 STGOPTIONS 構造体を参照してください。

[in] pSecurityDescriptor

予約;は 0 である必要があります。

[in] riid

返すインターフェイスポインターの GUID を指定する値。 IStorage インターフェイスを取得するIID_IStorageまたは IPropertySetStorage インターフェイスを取得するためのIID_IPropertySetStorageのヘッダー指定値を指定することもできます。

[out] ppObjectOpen

開かれたストレージオブジェクト上のインターフェイスのポインターを受け取るインターフェイスポインター変数のアドレス。操作が失敗した場合は NULL が 含まれます。

戻り値

この関数は、 HRESULT でラップされたファイルシステムエラーまたはシステムエラーを返すこともできます。詳細については、「エラー処理戦略」および「不明なエラーの処理」を参照してください。

注釈

StgOpenStorageEx は StgOpenStorage 関数のスーパーセットであり、新しいコードで使用する必要があります。構造化ストレージに対する今後の機能強化は、この関数を通じて公開される予定です。サポートされているプラットフォームの詳細については、「要件」セクションを参照してください。

StgOpenStorageEx 関数は、grfMode パラメーターのアクセスモードに従って指定されたルートストレージオブジェクトを開き、成功した場合は ppObjectOpen パラメーターで開かれたストレージオブジェクトのインターフェイスポインターを提供します。この関数を使用して、 IStorage 複合ファイルの実装、 IPropertySetStorage 複合ファイルの実装、または
IPropertySetStorage の NTFS ファイルシステムの実装。

ファイルを開くと、ファイルの種類とファイルが格納されているドライブの種類で指定した STGFMT フラグに応じて、構造化ストレージの実装が選択されます。

StgOpenStorageEx 関数を使用して、構造化ストレージドキュメントのルートストレージ、またはプロパティセットをサポートするすべてのファイルのプロパティセットストレージにアクセスします。さまざまな STGFMT 値でサポートされているインターフェイス識別子 (ID) の詳細については、「 STGFMT」を参照してください。

NTFS プロパティセットの実装にアクセスするためにこの関数を使用してファイルを開くと、特別な共有規則が適用されます。詳細については、「 IPropertySetStorage-NTFS の実装」を参照してください。

複合ファイルをトランザクションモードで開く場合は、STGM_TRANSACTEDを指定し、読み取り専用モードで、STGM_READを指定することで、返されるストレージオブジェクトを変更できます。たとえば、 IStorage::CreateStream を呼び出す可能性があります。ただし、 IStorage::Commit を呼び出すことで、これらの変更をコミットすることはできません。そのため、このような変更は失われます。

この関数の grfMode パラメーターで、STGM_CREATE、STGM_DELETEONRELEASE、またはSTGM_CONVERTフラグを使用することはできません。

サブストレージのないストレージオブジェクトを保存するための単純モードをサポートするために、 StgOpenStorageEx 関数は 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

簡易モードとシングルライター/マルチリーダーモードの詳細については、「 STGM 定数」を参照してください。

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

要件

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