StgCreateStorageEx

IStorage または IPropertySetStorage インターフェイスの提供された実装を使用して新しいストレージオブジェクトを作成する。

StgCreateStorageEx pwcsName, grfMode, stgfmt, grfAttrs, pStgOptions, pSecurityDescriptor, riid, ppObjectOpen

pwcsName : [wstr] 作成するファイルのパスへのポインタ。これは解釈されずにファイルシステムに渡される。これは相対名または NULL でもよい。NULL の場合、一意の名前で一時ファイルが割り当てられる。NULL でない場合、文字列のサイズは MAX_PATH 文字を超えてはならない。
grfMode : [int] 新しいストレージオブジェクトを開くときに使用するアクセスモードを指定する値。詳細については STGM Constants を参照のこと。呼び出し元がトランザクションモードと STGM_CREATE または STGM_CONVERT を一緒に指定した場合、上書きまたは変換はルートストレージに対して commit 操作が呼び出されたときに発生する。ルートストレージオブジェクトに対して IStorage::Commit が呼び出されなかった場合、ファイルの以前の内容が復元される。STGM_CREATE および STGM_CONVERT は STGM_NOSNAPSHOT フラグと組み合わせることができない。これは、トランザクションモードでファイルを上書きまたは変換する際にスナップショットコピーが必要となるためである。
stgfmt : [int] ストレージファイル形式を指定する値。詳細については STGFMT 列挙を参照のこと。
grfAttrs : [int] stgfmt パラメータの値に依存する値。
pStgOptions : [var] pStgOptions パラメータは stgfmt パラメータが STGFMT_DOCFILE に設定されている場合のみ有効である。stgfmt パラメータが STGFMT_DOCFILE に設定されている場合、pStgOptions は STGOPTIONS 構造体を指す。これはセクタサイズなどのストレージオブジェクトの機能を指定する。このパラメータは NULL でもよく、その場合は既定の 512 バイトのセクタサイズでストレージオブジェクトが作成される。NULL でない場合、ulSectorSize メンバーは 512 または 4096 のいずれかに設定する必要がある。4096 に設定された場合、grfMode パラメータに STGM_SIMPLE を指定することはできない。usVersion メンバーは StgCreateStorageEx を呼び出す前に設定しなければならない。詳細については STGOPTIONS を参照のこと。
pSecurityDescriptor : [int] ファイルが作成されるときに ACL を設定できるようにする。NULL でない場合、SECURITY_ATTRIBUTES 構造体へのポインタである必要がある。ファイルに ACL を設定する方法については CreateFile を参照のこと。Windows Server 2003、Windows 2000 Server、Windows XP、Windows 2000 Professional：値は NULL でなければならない。
riid : [var] 返されるインターフェイスポインタのインターフェイス識別子（IID）を指定する値。この IID は IStorage インターフェイスまたは IPropertySetStorage インターフェイスのものでよい。
ppObjectOpen : [var] 新しいストレージオブジェクト上のインターフェイスへのポインタを受け取るインターフェイスポインタ変数へのポインタ。操作が失敗した場合は NULL を含む。

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

解説

IStorage または IPropertySetStorage
インターフェイスの提供された実装を使用して新しいストレージオブジェクトを作成する。

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

[備考]
アプリケーションがそのファイルを変更するとき、通常は元のコピーを作成する。StgCreateStorageEx 関数はコピーを作成する 1
つの方法である。この関数は暗号化ファイルシステム（EFS）の複製 API
と間接的に動作する。この関数を使用するときは、STGOPTIONS
構造体でファイルストレージのオプションを設定する必要がある。StgCreateStorageEx は StgCreateDocfile
関数のスーパーセットであり、新しいコードでは使用すべきである。構造化ストレージへの今後の拡張は StgCreateStorageEx
関数を通じて公開される。サポートされるプラットフォームについては次の Requirements
セクションを参照のこと。StgCreateStorageEx 関数はシステムが提供する構造化ストレージ実装の 1
つを使用して新しいストレージオブジェクトを作成する。この関数は IStorage 複合ファイル実装、IPropertySetStorage
複合ファイル実装、または IPropertySetStorage NTFS
実装を取得するために使用できる。新しいファイルが作成されるとき、使用されるストレージ実装は指定するフラグとファイルが格納されているドライブの種類に依存する。詳細については
STGFMT 列挙を参照のこと。StgCreateStorageEx はファイルが存在しない場合に作成する。存在する場合、grfMode
パラメータでの STGM_CREATE、STGM_CONVERT、STGM_FAILIFTHERE
フラグの使用方法が処理方法を示す。これらの値の詳細については STGM Constants
を参照のこと。直接モード（STGM_TRANSACTED フラグを指定しないことで示される）で grfMode パラメータに
STGM_READ モードを指定することは無効である。この関数は既存のファイルを開くために使用できない。代わりに
StgOpenStorageEx 関数を使用する。StgCreateStorageEx
関数を使用して、構造化ストレージドキュメントのルートストレージや、プロパティセットをサポートする任意のファイルのプロパティセットストレージにアクセスできる。さまざまな
STGFMT 値に対してどの IID がサポートされているかについては STGFMT のドキュメントを参照のこと。NTFS
プロパティセット実装にアクセスするためにこの関数でファイルが作成される場合、特別な共有ルールが適用される。詳細については
IPropertySetStorage-NTFS Implementation
を参照のこと。複合ファイルがトランザクションモード（STGM_TRANSACTED を指定）と読み取り専用モード（STGM_READ
を指定）で作成される場合、返されたストレージオブジェクトに変更を加えることが可能である。たとえば
IStorage::CreateStream を呼び出すことができる。しかし、IStorage::Commit
を呼び出してそれらの変更をコミットすることはできない。したがって、そのような変更は失われる。STGM_SIMPLE
を指定すると、複数のストリームと no storages
を必要とするアプリケーションを伴う限定的だが頻繁に使用されるケースで複合ファイルオブジェクトのはるかに高速な実装を提供する。詳細については
STGM Constants を参照のこと。STGM_SIMPLE が指定されている場合に STGM_TRANSACTED
を指定することは無効である。シンプルモードは IStorage
上のすべてのメソッドをサポートしない。具体的にはシンプルモードでサポートされる IStorage メソッドは
CreateStream、Commit、SetClass、および COM IUnknown メソッドの
QueryInterface、AddRef、Release である。さらに SetElementTimes は NULL
名で対応されており、アプリケーションがルートストレージに時刻を設定できる。IStorage の他のすべてのメソッドは
STG_E_INVALIDFUNCTION を返す。grfMode パラメータが STGM_TRANSACTED
を指定しており、pwcsName
パラメータで指定された名前のファイルがまだ存在しない場合、ファイルは即座に作成される。アクセス制御されたファイルシステムでは、呼び出し元は複合ファイルが作成されるファイルシステムディレクトリへの書き込み権限を持たなければならない。STGM_TRANSACTED
が指定されておらず STGM_CREATE
が指定されている場合、新しいファイルを作成する前に同じ名前の既存ファイルが破棄される。pwcsName パラメータに NULL
値を渡すことで、StgCreateStorageEx
を使用して一時的な複合ファイルを作成することもできる。ただし、これらのファイルは、システムが提供する一意の名前（おそらくユーザにとって意味のない名前）を持つという意味でのみ一時的である。STGM_DELETEONRELEASE
が grfMode パラメータに指定されていない限り、終了時に一時ファイルを削除する責任は呼び出し元にある。これらのフラグの詳細については
STGM Constants を参照のこと。

情報