CREATEFILE3_EXTENDED_PARAMETERS構造体 (fileapi.h)

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

構文

typedef struct _CREATEFILE3_EXTENDED_PARAMETERS {
  DWORD                 dwSize;
  DWORD                 dwFileAttributes;
  DWORD                 dwFileFlags;
  DWORD                 dwSecurityQosFlags;
  LPSECURITY_ATTRIBUTES lpSecurityAttributes;
  HANDLE                hTemplateFile;
} CREATEFILE3_EXTENDED_PARAMETERS, *PCREATEFILE3_EXTENDED_PARAMETERS, *LPCREATEFILE3_EXTENDED_PARAMETERS;

メンバー

dwSize

この構造体のサイズを格納 sizeof(CREATEFILE3_EXTENDED_PARAMETERS)。

dwFileAttributes

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

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

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

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

dwFileFlags

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

dwSecurityQosFlags

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

lpSecurityAttributes

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

このパラメーターは NULLできます。

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

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

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

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

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

hTemplateFile

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

このパラメーターは NULLできます。

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

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

注釈

CREATEFILE3_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 ハンドル

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

必要条件

こちらもご覧ください

CreateFile3

ファイル管理構造