StgCreateStorageEx 関数 (coml2api.h)

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

StgCreateStorageEx 関数は、IStorage インターフェイスまたは IPropertySetStorage インターフェイスに対して提供された実装を使用して、新しいストレージオブジェクトを作成します。既存のファイルを開くには、代わりに StgOpenStorageEx 関数を使用します。

Windows 2000、Windows Server 2003、および Windows XP 用に作成されたアプリケーションでは、強化された Windows 2000 および Windows XP 構造化ストレージ機能を利用するには、StgCreateDocfile ではなく StgCreateStorageEx を使用する必要があります。

構文

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

パラメーター

[in] pwcsName

作成するファイルのパスへのポインター。これは、解釈されていないファイルシステムに渡されます。相対名または NULL を指定できます。 NULL の場合、一時ファイルは一意の名前で割り当てられます。 NULL 以外の場合、文字列サイズはMAX_PATH文字を超えることはできません。

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

[in] grfMode

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

[in] stgfmt

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

[in] grfAttrs

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

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

[in] pStgOptions

pStgOptions パラメーターは、stgfmt パラメーターが STGFMT_DOCFILE に設定されている場合にのみ有効です。 stgfmt パラメーターが STGFMT_DOCFILE に設定されている場合、pStgOptions は STGOPTIONS 構造体を指します。これは、セクターサイズなどのストレージオブジェクトの機能を指定します。このパラメーターは NULL で、既定のセクターサイズが 512 バイトのストレージオブジェクトを作成します。 NULL 以外の場合、ulSectorSize メンバーは 512 または 4096 のいずれかに設定する必要があります。 4096 に設定した場合、 grfMode パラメーターにSTGM_SIMPLEを指定できません。 usVersion メンバーは、StgCreateStorageEx を呼び出す前に設定する必要があります。詳細については、「 STGOPTIONS」を参照してください。

[in] pSecurityDescriptor

ファイルの作成時に ACL を設定できるようにします。 NULL でない場合は、SECURITY_ATTRIBUTES構造体へのポインターである必要があります。ファイルに ACL を設定する方法については、「 CreateFile 」を参照してください。

Windows Server 2003、Windows 2000 Server、Windows XP、Windows 2000 Professional: 値は NULL である必要があります。

[in] riid

返すインターフェイスポインターのインターフェイス識別子 (IID) を指定する値。この IID は、 IStorage インターフェイスまたは IPropertySetStorage インターフェイスの場合があります。

[out] ppObjectOpen

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

戻り値

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

解説

アプリケーションがファイルを変更すると、通常は元のファイルのコピーが作成されます。 StgCreateStorageEx 関数は、コピーを作成する 1 つの方法です。この関数は、暗号化ファイルシステム (EFS) 重複 API で間接的に動作します。この関数を使用する場合は、 STGOPTIONS 構造体のファイルストレージのオプションを設定する必要があります。

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

StgCreateStorageEx 関数は、システム提供の構造化ストレージ実装のいずれかを使用して、新しいストレージオブジェクトを作成します。この関数を使用して、
IStorage 複合ファイル実装、 IPropertySetStorage 複合ファイル実装、または IPropertySetStorage NTFS 実装を取得します。

新しいファイルが作成されるとき、使用されるストレージの実装は、指定したフラグと、ファイルが格納されるドライブの種類によって異なります。詳細については、 STGFMT 列挙を参照してください。

StgCreateStorageEx は、ファイルが存在しない場合に作成します。存在する場合、 grfMode パラメーターでSTGM_CREATE、STGM_CONVERT、およびSTGM_FAILIFTHERE フラグを使用すると、続行する方法が示されます。これらの値の詳細については、「 STGM 定数」を参照してください。 grfMode パラメーターでSTGM_READ モードを指定することは、直接モードでは無効です (直接モードは、STGM_TRANSACTED フラグを指定しないことで示されます)。この関数を使用して既存のファイルを開くことはできません。代わりに StgOpenStorageEx 関数を使用してください。

StgCreateStorageEx 関数を使用すると、構造化ストレージドキュメントのルートストレージ、またはプロパティセットをサポートする任意のファイルのプロパティセットストレージにアクセスできます。さまざまな STGFMT 値でサポートされる IID については、 STGFMT のドキュメントを参照してください。

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

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

STGM_SIMPLEを指定すると、複合ファイルオブジェクトの実装が非常に高速になりますが、複数のストリームと記憶域のない複合ファイルの実装を必要とするアプリケーションを含む場合によく使用されます。詳細については、「 STGM 定数」を参照してください。 STGM_SIMPLEが指定されている場合、そのSTGM_TRANSACTEDを指定することはできません。

簡易モードでは、 IStorage のすべてのメソッドがサポートされているわけではありません。具体的には、単純モードでは、サポートされている IStorage メソッドは、CreateStream、Commit、SetClass のほか、QueryInterface、AddRef、Release の COM IUnknown メソッドです。さらに、 SetElementTimes は NULL 名でサポートされているため、アプリケーションはルートストレージで時刻を設定できます。 IStorage の他のすべてのメソッドは、STG_E_INVALIDFUNCTIONを返します。

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

StgCreateStorageEx を使用して、pwcsName パラメーターに NULL 値を渡すことで、一時複合ファイルを作成することもできます。ただし、これらのファイルは、システムによって提供される一意の名前 (おそらくユーザーにとって意味のない名前) を持っているという意味でのみ一時的です。呼び出し元は、 grfMode パラメーターにSTGM_DELETEONRELEASE指定されていない限り、一時ファイルの終了時に削除します。これらのフラグの詳細については、「 STGM 定数」を参照してください。

要件


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

次の方法で共有

StgCreateStorageEx 関数 (coml2api.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

フィードバック

その他のリソース