StgOpenStorageEx 関数 (coml2api.h)

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

構文

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 定数」を参照してください。

要件

こちらもご覧ください

複合ファイル

IStorage

STGFMT

STGM 定数

STGOPTIONS

StgCreateDocfile

StgCreateStorageEx

StgOpenStorage