CREATEFILE2_EXTENDED_PARAMETERS
構造体サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。
フィールド
| フィールド | 型 | サイズ | x64 | x86 | 説明 | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| dwSize | DWORD | 4 | +0 | +0 | この構造体のサイズ (sizeof(CREATEFILE2_EXTENDED_PARAMETERS)) を格納します。 | ||||||||||||||||||||||||||||
| dwFileAttributes | DWORD | 4 | +4 | +4 | ファイルまたはデバイスの属性とフラグです。ファイルでは FILE_ATTRIBUTE_NORMAL が最も一般的な既定値です。 このパラメーターには、利用可能なファイル属性 (FILE_ATTRIBUTE_*) の任意の組み合わせを指定できます。他のファイル属性を指定すると、FILE_ATTRIBUTE_NORMAL は上書きされます。 メモ
CreateFile2 が既存のファイルを開く場合、通常はファイルフラグと既存ファイルのファイル属性が組み合わされ、dwFlagsAndAttributes の一部として指定されたファイル属性は無視されます。特殊なケースについては、ファイルの作成と開く操作 で詳しく説明されています。 以下のファイル属性とフラグの一部は、ファイルにのみ適用され、CreateFile2 が開くことのできる他のすべての種類のデバイスに必ずしも適用されるとは限りません。詳細については、 ファイル属性へのより高度なアクセスについては、SetFileAttributes を参照してください。すべてのファイル属性の値と説明の完全な一覧については、ファイル属性定数 を参照してください。
| ||||||||||||||||||||||||||||
| dwFileFlags | DWORD | 4 | +8 | +8 | このパラメーターには、ファイルまたはデバイスのキャッシュ動作、アクセスモード、その他の特殊な目的を制御するためのフラグ (FILE_FLAG_*) の組み合わせを指定できます。
| ||||||||||||||||||||||||||||
| dwSecurityQosFlags | DWORD | 4 | +12 | +12 | dwSecurityQosFlags パラメーターは SQOS 情報を指定します。詳細については、偽装レベル を参照してください。 | ||||||||||||||||||||||||||||
| lpSecurityAttributes | SECURITY_ATTRIBUTES* | 8/4 | +16 | +16 | SECURITY_ATTRIBUTES 構造体へのポインターです。この構造体には、独立しているものの互いに関連する 2 つのデータメンバー、すなわち省略可能なセキュリティ記述子と、返されたハンドルを子プロセスが継承できるかどうかを決定するブール値が含まれます。 このパラメーターには NULL を指定できます。 このパラメーターが NULL の場合、CreateFile2 が返すハンドルは、アプリケーションが作成する子プロセスに継承されず、返されたハンドルに関連付けられたファイルまたはデバイスには既定のセキュリティ記述子が割り当てられます。 構造体の lpSecurityDescriptor メンバーは、ファイルまたはデバイスの SECURITY_DESCRIPTOR を指定します。このメンバーが NULL の場合、返されたハンドルに関連付けられたファイルまたはデバイスには既定のセキュリティ記述子が割り当てられます。 CreateFile2 は、既存のファイルまたはデバイスを開くときには lpSecurityDescriptor メンバーを無視しますが、bInheritHandle メンバーは引き続き使用します。 構造体の bInheritHandle メンバーは、返されたハンドルを継承できるかどうかを指定します。 詳細については、CreateFile2 のトピックの解説セクションを参照してください。 | ||||||||||||||||||||||||||||
| hTemplateFile | HANDLE | 8/4 | +24 | +20 | GENERIC_READ アクセス権を持つテンプレートファイルへの有効なハンドルです。テンプレートファイルは、作成されるファイルにファイル属性と拡張属性を提供します。 このパラメーターには NULL を指定できます。 既存のファイルを開く場合、CreateFile2 はこのパラメーターを無視します。 新しい暗号化ファイルを開く場合、そのファイルは親ディレクトリから随意アクセス制御リストを継承します。詳細については、ファイルの暗号化 を参照してください。 |
公式ドキュメント
CreateFile2 用の省略可能な拡張パラメーターを格納します。
解説(Remarks)
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 と非同期 I/O を参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
各言語での定義
#include <windows.h>
// CREATEFILE2_EXTENDED_PARAMETERS (x64 32 / x86 24 バイト)
typedef struct CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
SECURITY_ATTRIBUTES* lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS;using System;
using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct CREATEFILE2_EXTENDED_PARAMETERS
{
public uint dwSize;
public uint dwFileAttributes;
public uint dwFileFlags;
public uint dwSecurityQosFlags;
public IntPtr lpSecurityAttributes;
public IntPtr hTemplateFile;
}Imports System.Runtime.InteropServices
<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure CREATEFILE2_EXTENDED_PARAMETERS
Public dwSize As UInteger
Public dwFileAttributes As UInteger
Public dwFileFlags As UInteger
Public dwSecurityQosFlags As UInteger
Public lpSecurityAttributes As IntPtr
Public hTemplateFile As IntPtr
End Structureimport ctypes
from ctypes import wintypes
class CREATEFILE2_EXTENDED_PARAMETERS(ctypes.Structure):
_fields_ = [
("dwSize", wintypes.DWORD),
("dwFileAttributes", wintypes.DWORD),
("dwFileFlags", wintypes.DWORD),
("dwSecurityQosFlags", wintypes.DWORD),
("lpSecurityAttributes", ctypes.c_void_p),
("hTemplateFile", ctypes.c_void_p),
]#[repr(C)]
pub struct CREATEFILE2_EXTENDED_PARAMETERS {
pub dwSize: u32,
pub dwFileAttributes: u32,
pub dwFileFlags: u32,
pub dwSecurityQosFlags: u32,
pub lpSecurityAttributes: *mut core::ffi::c_void,
pub hTemplateFile: *mut core::ffi::c_void,
}import "golang.org/x/sys/windows"
type CREATEFILE2_EXTENDED_PARAMETERS struct {
dwSize uint32
dwFileAttributes uint32
dwFileFlags uint32
dwSecurityQosFlags uint32
lpSecurityAttributes uintptr
hTemplateFile uintptr
}type
CREATEFILE2_EXTENDED_PARAMETERS = record
dwSize: DWORD;
dwFileAttributes: DWORD;
dwFileFlags: DWORD;
dwSecurityQosFlags: DWORD;
lpSecurityAttributes: Pointer;
hTemplateFile: Pointer;
end;const CREATEFILE2_EXTENDED_PARAMETERS = extern struct {
dwSize: u32,
dwFileAttributes: u32,
dwFileFlags: u32,
dwSecurityQosFlags: u32,
lpSecurityAttributes: ?*anyopaque,
hTemplateFile: ?*anyopaque,
};type
CREATEFILE2_EXTENDED_PARAMETERS {.bycopy.} = object
dwSize: uint32
dwFileAttributes: uint32
dwFileFlags: uint32
dwSecurityQosFlags: uint32
lpSecurityAttributes: pointer
hTemplateFile: pointerstruct CREATEFILE2_EXTENDED_PARAMETERS
{
uint dwSize;
uint dwFileAttributes;
uint dwFileFlags;
uint dwSecurityQosFlags;
void* lpSecurityAttributes;
void* hTemplateFile;
}HSP用 定義
HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; CREATEFILE2_EXTENDED_PARAMETERS サイズ: 24 バイト(x86)
dim st, 6 ; 4byte整数×6(構造体サイズ 24 / 4 切り上げ)
; dwSize : DWORD (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; dwFileAttributes : DWORD (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; dwFileFlags : DWORD (+8, 4byte) st.2 = 値 / 値 = st.2 (lpoke/lpeek も可)
; dwSecurityQosFlags : DWORD (+12, 4byte) st.3 = 値 / 値 = st.3 (lpoke/lpeek も可)
; lpSecurityAttributes : SECURITY_ATTRIBUTES* (+16, 4byte) varptr(st)+16 を基点に操作(4byte:入れ子/配列)
; hTemplateFile : HANDLE (+20, 4byte) st.5 = 値 / 値 = st.5 (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; CREATEFILE2_EXTENDED_PARAMETERS サイズ: 32 バイト(x64)
dim st, 8 ; 4byte整数×8(構造体サイズ 32 / 4 切り上げ)
; dwSize : DWORD (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; dwFileAttributes : DWORD (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; dwFileFlags : DWORD (+8, 4byte) st.2 = 値 / 値 = st.2 (lpoke/lpeek も可)
; dwSecurityQosFlags : DWORD (+12, 4byte) st.3 = 値 / 値 = st.3 (lpoke/lpeek も可)
; lpSecurityAttributes : SECURITY_ATTRIBUTES* (+16, 8byte) varptr(st)+16 を基点に操作(8byte:入れ子/配列)
; hTemplateFile : HANDLE (+24, 8byte) qpoke st,24,値 / qpeek(st,24) ※IronHSPのみ。3.7/3.8は lpoke st,24,下位 : lpoke st,28,上位
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global CREATEFILE2_EXTENDED_PARAMETERS
#field int dwSize
#field int dwFileAttributes
#field int dwFileFlags
#field int dwSecurityQosFlags
#field intptr lpSecurityAttributes
#field intptr hTemplateFile
#endstruct
stdim st, CREATEFILE2_EXTENDED_PARAMETERS ; NSTRUCT 変数を確保
st->dwSize = 100
mes "dwSize=" + st->dwSize