StgCreateDocfile 関数 (coml2api.h)

StgCreateDocfile 関数は、IStorage インターフェイスの COM 提供の複合ファイル実装を使用して、新しい複合ファイル ストレージ オブジェクトを作成します。

構文

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

パラメーター

[in] pwcsName

作成される複合ファイルの null で終わる Unicode 文字列名へのポインター。 これは、解釈されていないファイル システムに渡されます。 相対名または NULL を指定できます。 NULL の場合、一時複合ファイルは一意の名前で割り当てられます。

[in] grfMode

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

[in] reserved

今後使用するために予約されています。0 にする必要があります。

[out] ppstgOpen

新しいストレージ オブジェクトへの IStorage ポインターの場所へのポインター。

戻り値

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

注釈

StgCreateDocfile 関数は、IStorage インターフェイスの COM 提供の複合ファイル実装を使用して、新しいストレージ オブジェクトを作成します。 開いている複合ファイルの名前は、 IStorage::Stat メソッドを呼び出すことで取得できます。

ファイルが存在しない場合は、StgCreateDocfile によって作成されます。 存在する場合、 grfMode パラメーターでSTGM_CREATE、STGM_CONVERT、およびSTGM_FAILIFTHERE フラグを使用すると、続行する方法が示されます。 詳細については、「 STGM 定数」を参照してください。

複合ファイルがトランザクション モードで開かれている場合 ( grfMode パラメーターはSTGM_TRANSACTEDを指定します)、この名前のファイルが既に存在する場合、すべての未処理の変更がコミットされるまで、既存のファイルは変更されません。 呼び出し元のプロセスに既存のファイルへの書き込みアクセス権がない場合 (ファイル システムのアクセス制御のため)、 grfMode パラメーターはSTGM_WRITEまたはSTGM_READWRITEではなく、STGM_READのみを指定できます。 結果として得られる新しいオープン複合ファイルは引き続き書き込むことができますが、後続のコミット操作は失敗します (トランザクション・モードでは、書き込み権限はコミット時に適用されます)。

STGM_SIMPLEを指定すると、限定的で頻繁に使用されるケースで、複合ファイル オブジェクトの実装がはるかに高速になります。 これは、複数のストリームとストレージのない複合ファイルの実装を必要とするアプリケーションで使用できます。 簡易モードでは、 IStorage のすべてのメソッドがサポートされているわけではありません。 詳細については、「 STGM 定数」を参照してください。

grfMode パラメーターがSTGM_TRANSACTEDを指定し、pwcsName パラメーターで指定された名前のファイルがまだ存在しない場合、ファイルはすぐに作成されます。 アクセス制御ファイル システムでは、呼び出し元は、複合ファイルが作成されるファイル システム ディレクトリに書き込みアクセス許可を持っている必要があります。 STGM_TRANSACTEDを指定せず、STGM_CREATEを指定すると、新しいファイルが作成される前に、同じ名前の既存のファイルが破棄されます。

StgCreateDocfile を使用すると、pwcsName パラメーターに NULL 値を渡すことで、一時複合ファイルを作成できます。 ただし、これらのファイルは、システム指定の一意の名前 (ユーザーにとって意味のない名前) を持っているという意味でのみ一時的です。 呼び出し元は、 grfMode パラメーターにSTGM_DELETEONRELEASE指定されていない限り、一時ファイルの終了時に削除します。

要件

こちらもご覧ください

STGM 定数

StgCreateDocFileOnILockBytes

StgCreateStorageEx