CREATEFILE2_EXTENDED_PARAMETERS構造体 (fileapi.h)

CreateFile2 の省略可能な拡張パラメーターが含まれます。

構文

typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
  DWORD                 dwSize;
  DWORD                 dwFileAttributes;
  DWORD                 dwFileFlags;
  DWORD                 dwSecurityQosFlags;
  LPSECURITY_ATTRIBUTES lpSecurityAttributes;
  HANDLE                hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;

メンバー

dwSize

この構造体 sizeof(CREATEFILE2_EXTENDED_PARAMETERS)のサイズ () を格納します。

dwFileAttributes

ファイルまたはデバイスの属性とフラグ FILE_ATTRIBUTE_NORMAL 、ファイルの最も一般的な既定値です。

このパラメーターには、使用可能なファイル属性 (FILE_ATTRIBUTE_*) の任意の組み合わせを含めることができます。 その他のすべてのファイル属性は、 FILE_ATTRIBUTE_NORMALをオーバーライドします。

次のファイル属性とフラグの一部は、ファイルにのみ適用される場合があり、 CreateFile2 が開くことができる他のすべての種類のデバイスとは限りません。 詳細については、リファレンス ページの「解説」セクションと「ファイルのCreateFile2作成と開く」を参照してください。

ファイル属性への高度なアクセスについては、「 SetFileAttributes」を参照してください。 値と説明を含むすべてのファイル属性の完全な一覧については、「 ファイル属性定数」を参照してください。

dwFileFlags

このパラメーターには、ファイルまたはデバイスのキャッシュ動作、アクセス モード、およびその他の特殊な目的のフラグを制御するためのフラグ (FILE_FLAG_*) の組み合わせを含めることができます。

dwSecurityQosFlags

dwSecurityQosFlags パラメーターは、SQOS 情報を指定します。 詳細については、「 偽装レベル」を参照してください。

lpSecurityAttributes

2 つの独立した関連データ メンバーを含む SECURITY_ATTRIBUTES 構造体へのポインター。省略可能なセキュリティ記述子と、返されたハンドルを子プロセスによって継承できるかどうかを決定するブール値。

このパラメーターは、NULL でもかまいません。

このパラメーターが NULL の場合、 CreateFile2 によって返されるハンドルは、アプリケーションが作成できる子プロセスによって継承できず、返されるハンドルに関連付けられているファイルまたはデバイスは既定のセキュリティ記述子を取得します。

構造体の lpSecurityDescriptor メンバーは、ファイルまたはデバイスの SECURITY_DESCRIPTOR を指定します。 このメンバーが NULL の場合、返されるハンドルに関連付けられているファイルまたはデバイスには、既定のセキュリティ記述子が割り当てられます。

CreateFile2 は、既存のファイルまたはデバイスを開くときに lpSecurityDescriptor メンバーを無視しますが、引き続き bInheritHandle メンバーを使用します。

構造体の bInheritHandle メンバーは、返されたハンドルを継承できるかどうかを指定します。

詳細については、 CreateFile2 トピックの「解説」セクションを参照してください。

hTemplateFile

GENERIC_READアクセス権を持つテンプレート ファイルへの有効なハンドル。 テンプレート ファイルは、作成するファイルにファイル属性と拡張属性を提供します。

このパラメーターは、NULL でもかまいません。

既存のファイルを開くと、 CreateFile2 はこのパラメーターを無視します。

新しい暗号化されたファイルを開くと、ファイルは親ディレクトリから随意アクセス制御リストを継承します。 詳細については、「 ファイルの暗号化」を参照してください。

解説

CREATEFILE2_EXTENDED_PARAMETERS構造体を使用するアプリケーションをコンパイルするには、_WIN32_WINNT マクロを 以降として0x0602定義します。 詳細については、「 Windows ヘッダーの使用」を参照してください。

キャッシュの動作

dwFileFlags メンバーに使用できるいくつかの値は、ハンドルに関連付けられているデータがシステムによってキャッシュされる方法を制御または影響するために使用されます。 これらは次のとおりです。

• FILE_FLAG_NO_BUFFERING
• FILE_FLAG_RANDOM_ACCESS
• FILE_FLAG_SEQUENTIAL_SCAN
• FILE_FLAG_WRITE_THROUGH
• FILE_ATTRIBUTE_TEMPORARY

これらのフラグが指定されていない場合、システムは既定の汎用キャッシュ スキームを使用します。 それ以外の場合、システム キャッシュはフラグごとに指定されたとおりに動作します。

これらのフラグの一部を組み合わせてはいけません。 たとえば、 FILE_FLAG_RANDOM_ACCESS と FILE_FLAG_SEQUENTIAL_SCAN を組み合わせると、自己破りになります。

FILE_FLAG_SEQUENTIAL_SCAN フラグを指定すると、シーケンシャル アクセスを使用して大きなファイルを読み取るアプリケーションのパフォーマンスが向上する可能性があります。 大きなファイルを主に順番に読み取るが、場合によっては小さなバイト範囲をスキップするアプリケーションでは、パフォーマンスの向上がさらに顕著になる可能性があります。 アプリケーションがランダム アクセスのためにファイル ポインターを移動した場合、最適なキャッシュ パフォーマンスは発生しない可能性が高くなります。 ただし、正しい操作は引き続き保証されます。

フラグFILE_FLAG_WRITE_THROUGHとFILE_FLAG_NO_BUFFERINGは独立しており、組み合わせることができます。

FILE_FLAG_WRITE_THROUGHが使用されていてもFILE_FLAG_NO_BUFFERINGも指定されていないため、システム キャッシュが有効になっている場合、データはシステム キャッシュに書き込まれますが、ディスクに遅延なくフラッシュされます。

システム キャッシュが有効でないように、FILE_FLAG_WRITE_THROUGHとFILE_FLAG_NO_BUFFERINGの両方が指定されている場合、データは Windows システム キャッシュを経由せずにすぐにディスクにフラッシュされます。 オペレーティング システムは、ハード ディスクのローカル ハードウェア キャッシュの書き込みスルーも永続メディアに要求します。

FILE_FLAG_NO_BUFFERING フラグを適切 に 使用するには、アプリケーションに関する特別な考慮事項が必要です。 詳細については、「 ファイル バッファリング」を参照してください。

また、FILE_FLAG_WRITE_THROUGHを介した書き込み要求により、NTFS は要求の処理に起因するメタデータ変更 (タイム スタンプの更新や名前変更操作など) をフラッシュします。 このため、FILE_FLAG_WRITE_THROUGH フラグは、書き込みごとに FlushFileBuffers 関数を呼び出すための代わりに、FILE_FLAG_NO_BUFFERING フラグと共に使用されることが多く、これにより、不要なパフォーマンスが低下する可能性があります。 これらのフラグを一緒に使用すると、これらの罰則が回避されます。 ファイルとメタデータのキャッシュに関する一般的な情報については、「 ファイル キャッシュ」を参照してください。

FILE_FLAG_NO_BUFFERINGをFILE_FLAG_OVERLAPPEDと組み合わせると、I/O はメモリ マネージャーの同期操作に依存しないため、フラグによって最大の非同期パフォーマンスが得られます。 ただし、データがキャッシュに保持されていないため、一部の I/O 操作には時間がかかります。 また、ファイル メタデータはキャッシュされたままになる場合があります (たとえば、空のファイルを作成する場合など)。 メタデータが確実にディスクにフラッシュされるようにするには、 FlushFileBuffers 関数を 使用します。

FILE_ATTRIBUTE_TEMPORARY属性を指定すると、ハンドルが閉じられた後にアプリケーションによって一時ファイルが削除されるため、十分なキャッシュ メモリが使用可能な場合、ファイル システムは大容量ストレージにデータを書き戻さないようにします。 その場合、システムはデータの書き込みを完全に回避できます。 前述のフラグと同じ方法でデータ キャッシュを直接制御することはありませんが、 FILE_ATTRIBUTE_TEMPORARY 属性は、書き込みを行わずにシステム キャッシュにできるだけ多くを保持するようにシステムに指示するため、特定のアプリケーションにとって問題になる可能性があります。

同期および非同期 I/O ハンドル

CreateFile2 では、同期または非同期のファイル ハンドルまたはデバイス ハンドルを作成できます。 同期ハンドルは、そのハンドルを使用した I/O 関数呼び出しが完了するまでブロックされるように動作しますが、非同期ファイル ハンドルを使用すると、I/O 操作が完了したかどうかにかかわらず、システムは I/O 関数呼び出しから直ちに戻すことができます。 前述のように、この同期と非同期の動作は、pCreateExParams パラメーターで渡されるCREATEFILE2_EXTENDED_PARAMETERS構造体の dwFileFlags メンバー内でFILE_FLAG_OVERLAPPEDを指定することによって決定されます。 非同期 I/O を使用する場合、いくつかの複雑さと潜在的な落とし穴があります。詳細については、「 同期および非同期 I/O」を参照してください。

要件

関連項目

CreateFile2

ファイル管理の構造体