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
| 属性 | 意味 |
|---|---|
|
ファイルはアーカイブする必要があります。 アプリケーションでは、この属性を使用して、バックアップまたは削除のためにファイルをマークします。 |
|
ファイルまたはディレクトリは暗号化されます。 ファイルの場合、これはファイル内のすべてのデータが暗号化されることを意味します。 ディレクトリの場合は、暗号化が新しく作成されたファイルとサブディレクトリの既定値であることを意味します。 詳細については、「File Encryption」を参照してください。
FILE_ATTRIBUTE_SYSTEM も指定されている場合、このフラグは無効です。 このフラグは、Windows の Home、Home Premium、Starter、または ARM エディションではサポートされていません。 Windows ストア アプリから呼び出された場合、このフラグはサポートされません。 |
|
ファイルは非表示になっています。 通常のディレクトリ 一覧には含めないでください。 |
|
整合性を使用して構成されたファイルまたはディレクトリ。 ファイルの場合、ファイル内のすべてのデータ ストリームに整合性があります。 ディレクトリの場合、呼び出し元が特に指定しない限り、新しく作成されたファイルとサブディレクトリの既定値は整合性です。
このフラグは、ReFS ファイル システムでのみサポートされます。 |
|
ファイルに他の属性が設定されていません。 この属性は、単独で使用する場合にのみ有効です。 |
|
ファイルのデータはすぐには使用できません。 この属性は、ファイル データがオフライン ストレージに物理的に移動されることを示します。 この属性は、階層型ストレージ管理ソフトウェアであるリモート ストレージによって使用されます。 アプリケーションでは、この属性を任意に変更しないでください。 |
|
ファイルは読み取り専用です。 アプリケーションはファイルを読み取ることができますが、書き込みや削除はできません。 |
|
ファイルは、オペレーティング システムの一部であるか、オペレーティング システムによって排他的に使用されます。 |
|
ファイルは一時ストレージに使用されています。
詳細については、このトピックの「キャッシュ動作」セクションを参照してください。 |
dwFileFlags
このパラメーターには、ファイルまたはデバイスのキャッシュ動作、アクセス モード、およびその他の特殊な目的のフラグを制御するためのフラグ (FILE_FLAG_*) の組み合わせを含めることができます。
| 旗 | 意味 |
|---|---|
|
バックアップ操作または復元操作のためにファイルが開かれているか、作成されています。 システムは、プロセスが SE_BACKUP_NAME および SE_RESTORE_NAME 特権を持っている場合に、呼び出し元のプロセスがファイル セキュリティ チェックをオーバーライドすることを保証します。 詳細については、「トークンでの権限の変更 ディレクトリへのハンドルを取得するには、このフラグを設定する必要があります。 ディレクトリ ハンドルは、ファイル ハンドルではなく一部の関数に渡すことができます。 詳細については、「解説」セクションを参照してください。 |
|
ファイルは、指定されたハンドルとその他の開いているハンドルまたは重複するハンドルを含む、すべてのハンドルが閉じられた直後に削除されます。
ファイルに対して開いているハンドルが存在する場合、FILE_SHARE_DELETE 共有モードですべて開かなければ、呼び出しは失敗します。 FILE_SHARE_DELETE 共有モードが指定されていない限り、ファイルに対する後続のオープン要求は失敗します。 |
|
デバイス マップは、DOS デバイス名とシステム内のデバイス間のマッピングであり、DOS 名を解決するときに使用されます。 システム内のユーザーごとに個別のデバイス マップが存在し、ユーザーは独自のデバイス マップを管理できます。 通常、偽装中は、偽装されたユーザーのデバイス マップが使用されます。 ただし、このフラグを設定すると、プロセス ユーザーのデバイス マップが代わりに使用されます。 |
|
ファイルまたはデバイスは、データの読み取りと書き込みのシステム キャッシュなしで開かれています。 このフラグは、ハード ディスク のキャッシュやメモリ マップされたファイルには影響しません。
|
|
ファイル データは要求されますが、引き続きリモート ストレージに配置する必要があります。 ローカル ストレージに転送しないでください。 このフラグは、リモート・ストレージ・システムで使用するために使用されます。 |
|
通常 このフラグは、CREATE_ALWAYS フラグと共に使用することはできません。 ファイルが再解析ポイントでない場合、このフラグは無視されます。 詳細については、「解説」セクションを参照してください。 |
|
ファイルが開き、ファイルの日和見ロック (oplock) が 1 つのアトミック操作として要求されています。 ファイル システムは、作成操作を実行する前に oplock をチェックし、結果が既存の oplock を中断する場合は、ERROR_CANNOT_BREAK_OPLOCK の最後のエラー コードで作成に失敗します。
このフラグを使用し、CreateFile2 関数の呼び出しが正常に返された場合、ファイル ハンドルに対して最初に実行する必要がある操作は、DeviceIOControl 関数を呼び出して oplock を要求し、FSCTL_REQUEST_OPLOCK または他の Opportunistic Lock Operationsを渡すことです。 oplock を要求する前に、ファイル ハンドルを使用して他のファイル システム操作を実行すると、デッドロックが発生する可能性があります。
メモ 最初に oplock を要求することなく、ファイル ハンドルで CloseHandle 関数を安全に呼び出すことができます。
|
|
非同期 I/O 用にファイルまたはデバイスが開かれているか、作成されています。
このハンドルで後続の I/O 操作が完了すると、OVERLAPPED 構造体で指定されたイベントがシグナル状態に設定されます。 このフラグを指定すると、ファイルを読み取りと書き込みの同時操作に使用できます。 このフラグが指定されていない場合、読み取りおよび書き込み関数の呼び出しで OVERLAPPED 構造体が指定されている場合でも、I/O 操作がシリアル化されます。 このフラグで作成されたファイル ハンドルを使用する場合の考慮事項については、このトピックの「同期および非同期 I/O ハンドル |
|
アクセスは POSIX 規則に従って行われます。 これには、名前付けをサポートするファイル システムの場合にのみ異なる名前を持つ複数のファイルを許可することが含まれます。 このフラグで作成されたファイルは、MS-DOS または 16 ビット Windows 用に書き込まれたアプリケーションではアクセスできない可能性があるため、このオプションを使用する場合は注意が必要です。 |
|
アクセスはランダムであることを意図しています。 システムは、ファイル キャッシュを最適化するためのヒントとしてこれを使用できます。
このフラグは、ファイル システムがキャッシュされた I/O と FILE_FLAG_NO_BUFFERINGをサポートしていない場合は影響を与えません。 詳細については、このトピックの「キャッシュ動作」セクションを参照してください。 |
|
ファイルまたはデバイスがセッション認識で開かれています。 このフラグが指定されていない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。 このフラグは、セッション 0 に含まれていない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。
Windows Server 2008 R2 および Windows Server 2008: このフラグは、Windows Server 2012 より前にはサポートされていません。 |
|
アクセスは、最初から最後まで順番に行われます。 システムは、ファイル キャッシュを最適化するためのヒントとしてこれを使用できます。
読み取りビハインド (つまり、後方スキャン) を使用する場合は、このフラグを使用しないでください。 このフラグは、ファイル システムがキャッシュされた I/O と FILE_FLAG_NO_BUFFERINGをサポートしていない場合は影響を与えません。 詳細については、このトピックの「キャッシュ動作」セクションを参照してください。 |
|
書き込み操作は中間キャッシュを経由せず、ディスクに直接移動します。
詳細については、このトピックの「キャッシュ動作 |
dwSecurityQosFlags
dwSecurityQosFlags パラメーターは、SQOS 情報を指定します。 詳細については、「偽装レベルの」を参照してください。
lpSecurityAttributes
2 つの独立した関連するデータ メンバーを含む SECURITY_ATTRIBUTES 構造体へのポインター。省略可能なセキュリティ記述子と、返されたハンドルを子プロセスで継承できるかどうかを決定するブール値。
このパラメーターは NULL
このパラメーターが NULL
構造体の lpSecurityDescriptor メンバーは、ファイルまたはデバイスの SECURITY_DESCRIPTOR を指定します。 このメンバーが NULL
CreateFile2
構造体の bInheritHandle メンバーは、返されたハンドルを継承できるかどうかを指定します。
詳細については、「CreateFile2」トピックの「解説」セクションを参照してください。
hTemplateFile
GENERIC_READ アクセス権を持つテンプレート ファイルへの有効なハンドル。 テンプレート ファイルは、作成されるファイルのファイル属性と拡張属性を提供します。
このパラメーターは NULL
既存のファイルを開くときに、CreateFile2
新しい暗号化されたファイルを開くと、ファイルは親ディレクトリから随意アクセス制御リストを継承します。 詳細については、「File Encryption」を参照してください。
備考
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を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows 8 [デスクトップ アプリ |UWP アプリ] |
| サポートされる最小サーバー | Windows Server 2012 [デスクトップ アプリ |UWP アプリ] |
| ヘッダー | fileapi.h (Windows.h を含む) |
関連項目
CreateFile2 の