StgCreateStorageEx 関数 (coml2api.h)

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 パラメーターの値に依存する値。

[in] pStgOptions

pStgOptions パラメーターは、stgfmt パラメーターが STGFMT_DOCFILE に設定されている場合にのみ有効です。 stgfmt パラメーターが STGFMT_DOCFILE に設定されている場合、pStgOptions は、セクター サイズなどのストレージ オブジェクトの機能を指定する、STGOPTIONS 構造体を指します。 このパラメーターは NULLできます。これにより、既定のセクター サイズが 512 バイトのストレージ オブジェクトが作成されます。 null以外の場合、ulSectorSize メンバーは 512 または 4096 のいずれかに設定する必要があります。 4096 に設定すると、grfMode パラメーターにSTGM_SIMPLEを指定できません。 stgCreateStorageExを呼び出す前に、usVersion メンバー 設定する必要があります。 詳細については、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 関数のスーパーセットであり、新しいコードで使用する必要があります。 Structured Storage の今後の機能強化は、StgCreateStorageEx 関数を通じて公開される予定です。 サポートされているプラットフォームの詳細については、次の要件セクションを参照してください。

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

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

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

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

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

必要条件

関連項目

CreateFile の

STGFMT

STGM 定数 を する

STGOPTIONS の

StgCreateDocFileOnILockBytes

StgCreateDocfile の

StgOpenStorageEx の