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 では、既存のファイルを開くと、通常、ファイル フラグと既存のファイルのファイル属性が結合され、dwFlagsAndAttributes の一部として指定されたファイル属性は無視されます。 特殊なケースについては、「 ファイルの作成と開き方」を参照してください。
次のファイル属性とフラグの一部は、ファイルにのみ適用される場合があり、 CreateFile2 が開くことができる他のすべての種類のデバイスとは限りません。 詳細については、リファレンス ページの「解説」セクションと「ファイルのCreateFile2作成と開く」を参照してください。
ファイル属性への高度なアクセスについては、「 SetFileAttributes」を参照してください。 値と説明を含むすべてのファイル属性の完全な一覧については、「 ファイル属性定数」を参照してください。
| 属性 | 説明 |
|---|---|
|
ファイルをアーカイブする必要があります。 アプリケーションでは、この属性を使用して、バックアップまたは削除の対象にファイルをマークします。 |
|
ファイルまたはディレクトリは暗号化されています。 ファイルの場合は、ファイルのすべてのデータが暗号化されています。 ディレクトリの場合、新しく作成されたファイルとサブディレクトリの既定値は暗号化であることを意味します。 詳細については、「 ファイルの暗号化」を参照してください。
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 名を解決するときに使用されます。 システム内のユーザーごとに個別のデバイス マップが存在し、ユーザーは独自のデバイス マップを管理できます。 通常、偽装中は、偽装されたユーザーのデバイス マップが使用されます。 ただし、このフラグを設定すると、代わりにプロセス ユーザーのデバイス マップが使用されます。 |
|
ファイルまたはデバイスは、データの読み取りと書き込みのシステム キャッシュなしで開かれています。 このフラグは、ハード ディスクキャッシュやメモリマップファイルには影響しません。
FILE_FLAG_NO_BUFFERING フラグを使用して CreateFile2 で開かれたファイルを正常に操作するには、厳密な要件があります。詳細については、「ファイル バッファリング」を参照してください。 |
|
ファイル データは要求されますが、引き続きリモート ストレージに配置する必要があります。 ローカル ストレージに転送しないでください。 このフラグは、リモート・ストレージ・システムで使用されます。 |
|
通常 の再解析ポイント 処理は行われません。 CreateFile2 は再解析ポイントを開こうとします。 ファイルを開くと、再解析ポイントを制御するフィルターが動作可能かどうかに関係なく、ファイル ハンドルが返されます。
このフラグは 、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 用に作成されたアプリケーションでは、このフラグで作成されたファイルにアクセスできない可能性があるため、このオプションを使用する場合は注意が必要です。 |
|
アクセスはランダムであることを目的としています。 システムはこれをヒントとしてファイルのキャッシュを最適化します。
ファイル・システムがキャッシュされた入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。 詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。 |
|
ファイルまたはデバイスがセッション認識で開かれています。 このフラグが指定されていない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。 このフラグは、セッション 0 にない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。
Windows Server 2008 R2 と Windows Server 2008: このフラグは、Windows Server 2012 より前はサポートされていません。 |
|
Access は、最初から最後まで順番に行われるよう意図されています。 システムはこれをヒントとしてファイルのキャッシュを最適化します。
このフラグは、読み取りビハインド (つまり、後方スキャン) を使用する場合は使用しないでください。 ファイル・システムがキャッシュされた入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。 詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。 |
|
書き込み操作は中間キャッシュを通過せず、ディスクに直接移動します。
詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。 |
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」を参照してください。
要件
| サポートされている最小のクライアント | Windows 8 [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2012 [デスクトップ アプリ |UWP アプリ] |
| Header | fileapi.h (Windows.h を含む) |