StgCreateDocfile

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

StgCreateDocfile pwcsName, grfMode, reserved, ppstgOpen

pwcsName : [wstr] 作成される複合ファイルの null 終端の Unicode 文字列名へのポインタ。これは解釈されずにファイルシステムに渡される。これは相対名または NULL でもよい。NULL の場合、一意の名前で一時的な複合ファイルが割り当てられる。
grfMode : [int] 新しいストレージオブジェクトを開くときに使用するアクセスモードを指定する。詳細については STGM Constants を参照のこと。呼び出し元がトランザクションモードと STGM_CREATE または STGM_CONVERT を一緒に指定した場合、上書きまたは変換はルートストレージに対して commit 操作が呼び出されたときに発生する。ルートストレージオブジェクトに対して IStorage::Commit が呼び出されなかった場合、ファイルの以前の内容が復元される。STGM_CREATE および STGM_CONVERT は STGM_NOSNAPSHOT フラグと組み合わせることができない。これは、トランザクションモードでファイルを上書きまたは変換する際にスナップショットコピーが必要となるためである。
reserved : [int] 将来の使用のために予約されており、ゼロでなければならない。
ppstgOpen : [var] 新しいストレージオブジェクトへの IStorage ポインタの場所へのポインタ。

(プラグイン / モジュール : ole32.dll)

解説

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

[戻り値]
StgCreateDocfile は HRESULT にラップされたファイルシステムエラーやシステムエラーも返すことがある。詳細については
Error Handling Strategies と Handling Unknown Errors を参照のこと。

[備考]
StgCreateDocfile 関数は、IStorage インターフェイスの COM
が提供する複合ファイル実装を使用して新しいストレージオブジェクトを作成する。開かれた複合ファイルの名前は IStorage::Stat
メソッドの呼び出しで取得できる。StgCreateDocfile はファイルが存在しない場合に作成する。存在する場合、grfMode
パラメータでの STGM_CREATE、STGM_CONVERT、STGM_FAILIFTHERE
フラグの使用方法が処理方法を示す。詳細については STGM Constants
を参照のこと。複合ファイルがトランザクションモード（grfMode パラメータが STGM_TRANSACTED
を指定）で開かれており、この名前のファイルがすでに存在する場合、未処理の変更がすべてコミットされるまで既存のファイルは変更されない。呼び出しプロセスが既存のファイルへの書き込みアクセスを欠いている場合（ファイルシステムのアクセス制御による）、grfMode
パラメータは STGM_READ のみを指定でき、STGM_WRITE や STGM_READWRITE
は指定できない。結果として新しく開かれた複合ファイルには書き込み可能だが、その後の commit
操作は失敗する（トランザクションモードでは、書き込み権限はコミット時に強制される）。STGM_SIMPLE
を指定すると、複数のストリームと no storages
を必要とするアプリケーションで頻繁に使用される限定的なケースで複合ファイルオブジェクトのはるかに高速な実装を提供する。シンプルモードは
IStorage 上のすべてのメソッドをサポートしない。詳細については STGM Constants を参照のこと。grfMode
パラメータが STGM_TRANSACTED を指定しており、pwcsName
パラメータで指定された名前のファイルがまだ存在しない場合、ファイルは即座に作成される。アクセス制御されたファイルシステムでは、呼び出し元は複合ファイルが作成されるファイルシステムディレクトリへの書き込み権限を持たなければならない。STGM_TRANSACTED
が指定されておらず STGM_CREATE
が指定されている場合、新しいファイルが作成される前に同じ名前の既存ファイルが破棄される。StgCreateDocfile は
pwcsName パラメータに NULL
値を渡すことで一時的な複合ファイルを作成するために使用できる。ただし、これらのファイルは、システムが提供する一意の名前（おそらくユーザにとって意味のない名前）を持つという意味でのみ一時的である。STGM_DELETEONRELEASE
が grfMode パラメータに指定されていない限り、終了時に一時ファイルを削除する責任は呼び出し元にある。

情報