CreateFile2 関数 (fileapi.h)
ファイルまたは I/O デバイスを作成または開きます。 最も一般的に使用される I/O デバイスは、ファイル、ファイル ストリーム、ディレクトリ、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、通信リソース、mailslot、パイプです。 この関数は、ファイルまたはデバイス、および指定されたフラグと属性に応じて、さまざまな種類の I/O のファイルまたはデバイスにアクセスするために使用できるハンドルを返します。
Windows ストア アプリから呼び出すと、CreateFile2
構文
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
パラメーター
[in] lpFileName
作成または開くファイルまたはデバイスの名前。
特殊なデバイス名の詳細については、「MS-DOS デバイス名の定義」を参照してください。
ファイル ストリームを作成するには、ファイルの名前、コロン、ストリームの名前を指定します。 詳細については、「ファイル ストリームの」を参照してください。
[in] dwDesiredAccess
ファイルまたはデバイスへの要求されたアクセス。読み取り、書き込み、両方、またはゼロとして要約できます)。
最も一般的に使用される値は、GENERIC_READ、GENERIC_WRITE、またはその両方 (GENERIC_READ | GENERIC_WRITE) です。 詳細については、「汎用アクセス権
このパラメーターが 0 の場合、アプリケーションは、そのファイルまたはデバイスにアクセスしなくても、ファイル、ディレクトリ、デバイス属性などの特定のメタデータ GENERIC_READ クエリを実行できます。
既に開いているハンドルを持つオープン要求で、dwShareMode パラメーターで指定された共有モードと競合するアクセス モードを要求することはできません。
詳細については、このトピックの「解説」セクションと ファイルの作成と開くを参照してください。
[in] dwShareMode
ファイルまたはデバイスの要求された共有モード。読み取り、書き込み、両方、削除、これらすべて、またはなしを指定できます (次の表を参照)。 属性または拡張属性へのアクセス要求は、このフラグの影響を受けません。
このパラメーターが 0 で、CreateFile2
開いているハンドルを持つ既存の要求で指定されているアクセス モードと競合する共有モードを要求することはできません。 CreateFile2 は失敗し、GetLastError 関数は ERROR_SHARING_VIOLATIONを返します。
別のプロセスがファイルまたはデバイスを開いている間にプロセスでファイルまたはデバイスを共有できるようにするには、次の値の 1 つ以上の互換性のある組み合わせを使用します。 このパラメーターと dwDesiredAccess パラメーターの有効な組み合わせの詳細については、「ファイルの作成と開く」を参照してください。
[in] dwCreationDisposition
存在する、または存在しないファイルまたはデバイスに対して実行するアクション。
ファイル以外のデバイスの場合、通常、このパラメーターは OPEN_EXISTINGに設定されます。
詳細については、「解説」セクションを参照してください。
このパラメーターは、組み合わせることができない次のいずれかの値である必要があります。
[in, optional] pCreateExParams
省略可能な CREATEFILE2_EXTENDED_PARAMETERS 構造体へのポインター。
戻り値
関数が成功した場合、戻り値は、指定されたファイル、デバイス、名前付きパイプ、またはメール スロットへの開いているハンドルです。
関数が失敗した場合、戻り値は INVALID_HANDLE_VALUE。 拡張エラー情報を取得するには、GetLastError
備考
CreateFile2 関数を使用するアプリケーションをコンパイルするには、_WIN32_WINNT マクロを 0x0602 以降として定義します。 詳細については、「Windows ヘッダーの使用」を参照してください。
CreateFile2 では、ファイルの相互作用、およびその他のほとんどの種類の I/O デバイスと、Windows 開発者が使用できるメカニズムがサポートされます。 このセクションでは、CreateFile2 をさまざまなコンテキストやさまざまな I/O の種類で使用する場合に、開発者が経験する可能性があるさまざまな問題について説明します。 テキストは、ファイル システム上の実際のファイルに格納されているデータを特に参照する場合にのみ、ファイル という単語の使用を試みます。 ただし、ファイル の一部の使用は、ファイルのようなメカニズムをサポートする I/O オブジェクトをより一般的に参照している可能性があります。
ファイル
CreateFile2によって返されるオブジェクト ハンドル
NTFS ファイル システムなどの一部のファイル システムでは、個々のファイルとディレクトリの圧縮または暗号化がサポートされています。 このサポートを持つマウントされたファイル システムを持つボリュームでは、新しいファイルは、そのディレクトリの圧縮属性と暗号化属性を継承します。
CreateFile2 を使用して、ファイルまたはディレクトリの圧縮、展開、または復号化を制御することはできません。 詳細については、「ファイルの作成と開き
bInheritHandle メンバー変数が FALSE(0 以外の値)されていない場合は、ハンドルを継承できます。 したがって、ハンドルを継承できない場合は、FALSE を するためにこの構造体メンバーを適切に初期化することが重要です。 - ファイルまたはディレクトリの既定のセキュリティ記述子のアクセス制御リスト (ACL) は、親ディレクトリから継承されます。
- ターゲット ファイル システムは、
lpSecurityDescriptor メンバーがそれらに影響を与えるために、ファイルとディレクトリのセキュリティをサポートする必要があります。これは、GetVolumeInformation使用して決定できます。
| テクノロジー | サポート |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 透過的フェールオーバー (TFO) | いいえ |
| SMB 3.0 とスケールアウト ファイル共有 (SO) | いいえ |
| クラスター共有ボリューム ファイル システム (CsvFS) | はい |
| 回復性のあるファイル システム (ReFS) | はい |
シンボリック リンクの動作の
この関数の呼び出しによってファイルが作成された場合、動作に変更はありません。 また、pCreateExParams パラメーターで渡される CREATEFILE2_EXTENDED_PARAMETERS 構造体の dwFileFlags メンバーの FILE_FLAG_OPEN_REPARSE_POINT フラグに関する次の情報を考慮してください。-
FILE_FLAG_OPEN_REPARSE_POINT が指定されている場合:
- 既存のファイルが開き、シンボリック リンクである場合、返されるハンドルはシンボリック リンクへのハンドルです。
- TRUNCATE_EXISTING または FILE_FLAG_DELETE_ON_CLOSE が指定されている場合、影響を受けるファイルはシンボリック リンクです。
-
FILE_FLAG_OPEN_REPARSE_POINT が指定されていない場合:
- 既存のファイルが開き、それがシンボリック リンクである場合、返されるハンドルはターゲットへのハンドルです。
- CREATE_ALWAYS、TRUNCATE_EXISTING、または FILE_FLAG_DELETE_ON_CLOSE が指定されている場合、影響を受けるファイルがターゲットです。
ファイル
ファイルの名前を変更または削除し、その後すぐに復元すると、システムはキャッシュで復元するファイル情報を検索します。 キャッシュされた情報には、短い名前と長い名前のペアと作成時間が含まれます。DeleteFile
dwDesiredAccess パラメーターは 0 にすることができ、アプリケーションが適切なセキュリティ設定で実行されている場合、アプリケーションはファイルにアクセスせずにファイル属性を照会できます。 これは、読み取り/書き込みアクセスのためにファイルを開かずにファイルの存在をテストしたり、ファイルまたはディレクトリに関するその他の統計情報を取得したりする場合に便利です。 GetFileInformationByHandle および
アプリケーションがネットワーク経由でファイルを作成する場合は、
詳細については、「ファイルの作成と開く」を参照してください。
ファイル ストリーム
NTFS ファイル システムでは、CreateFile2 を使用して、ファイル内に個別のストリームを作成できます。 詳細については、「ファイル ストリームの」を参照してください。ディレクトリ
アプリケーションは CreateFile2CreateFile2 を使用して FAT または FAT32 ファイル システム ボリュームの最適化中にディレクトリを開く場合は、MAXIMUM_ALLOWED アクセス権を指定しないでください。 この操作を行うと、ディレクトリへのアクセスが拒否されます。 代わりに、GENERIC_READ アクセス権を指定します。
詳細については、「ディレクトリ管理について」を参照してください。
物理ディスクとボリュームの
ディスクまたはボリュームへの直接アクセスは制限されます。CreateFile2 関数を使用すると、物理ディスク ドライブまたはボリュームを開くことができます。この関数は、DeviceIoControl 関数で使用できる直接アクセス 記憶装置 (RSS) ハンドルを返します。 これにより、パーティション テーブルなどのディスク メタデータなど、ディスクまたはボリュームに直接アクセスできます。 ただし、この種類のアクセスでは、ディスク ドライブまたはボリュームのデータ損失の可能性もあります。このメカニズムを使用したディスクへの書き込みが正しくないと、その内容がオペレーティング システムからアクセスできなくなる可能性があるためです。 データの整合性を確保するには、DeviceIoControl と、ファイル システム ハンドルではなく直接アクセス ハンドルを使用して他の API がどのように動作するかについて理解しておく必要があります。
このような呼び出しを成功させるには、次の要件を満たす必要があります。
- 呼び出し元には管理者特権が必要です。 詳細については、「特別な特権を使用した実行 」を参照してください。
- dwCreationDisposition パラメーターには、OPEN_EXISTING フラグが必要です。
- ボリュームまたはフロッピー ディスクを開く場合は、dwShareMode パラメーターに FILE_SHARE_WRITE フラグが必要です。
| 糸 | 意味 |
|---|---|
| "\\.\PhysicalDrive0" | 最初の物理ドライブを開きます。 |
| "\\.\PhysicalDrive2" | 3 番目の物理ドライブを開きます。 |
ボリュームの物理ドライブ識別子を取得するには、ボリュームのハンドルを開き、DeviceIoControl 関数を IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTSで呼び出します。 この制御コードは、ボリュームの 1 つ以上のエクステントごとにディスク番号とオフセットを返します。ボリュームは複数の物理ディスクにまたがる場合があります。
物理ドライブを開く例については、「DeviceIoControlの呼び出し」を参照してください。
ボリュームまたはリムーバブル メディア ドライブ (フロッピー ディスク ドライブやフラッシュ メモリサム ドライブなど) を開く場合、lpFileName 文字列
| 糸 | 意味 |
|---|---|
| "\\.\A:" | フロッピー ディスク ドライブ A を開きます。 |
| "\\.\C:" | C: ボリュームを開きます。 |
| "\\.\C:\" | C: ボリュームのファイル システムを開きます。 |
ボリューム名を参照してボリュームを開くこともできます。 詳細については、「ボリュームの名前付け
ボリュームには、1 つ以上のマウントされたファイル システムが含まれています。 ボリューム ハンドルは、CreateFile2でキャッシュされていないオプションが指定されていない場合でも、特定のファイル システムの判断
ファイル システムでは、データがキャッシュされていない場合でも、バッファーの配置が必要な場合と必要ない場合があります。 ただし、ボリュームを開くときにキャッシュされていないオプションが指定されている場合は、ボリューム上のファイル システムに関係なく、バッファーの配置が適用されます。 ボリューム ハンドルをキャッシュなしとして開き、キャッシュされていない I/O 制限に従うすべてのファイル システムで推奨されます。
チェンジャー デバイス
DeviceIoControl の IOCTL_CHANGER_* コントロール コード、チェンジャー デバイスへのハンドルを受け入れます。 チェンジャー デバイスを開くには、"\\.\Changerx" という形式のファイル名を使用します。ここで、x は、ゼロから始まる、開くデバイスを示す数値です。 C または C++ で記述されたアプリケーションで changer デバイス 0 を開くには、"\\\\.\\Changer0" というファイル名を使用します。テープ ドライブ
"\\.\TAPEx" という形式のファイル名を使用して、テープ ドライブを開くことができます。ここで、x は、テープ ドライブ 0 から始まる、開くドライブを示す番号です。 C または C++ で記述されたアプリケーションでテープ ドライブ 0 を開くには、"\\\\.\\TAPE0" というファイル名を使用します。詳細については、「バックアップ
通信リソース
CreateFile2 関数は、シリアル ポート COM1 などの通信リソースへのハンドルを作成できます。 通信リソースの場合、9 より大きい COM ポート番号を指定するには、"\.\COM10" という構文を使用します。 この構文は、COM ポート番号を指定できるすべてのポート番号とハードウェアに対して機能します。
コンソール
CreateFile2 関数は、コンソール入力 (CONIN$) へのハンドルを作成できます。 継承または重複の結果としてプロセスに開いているハンドルがある場合は、アクティブな画面バッファー (CONOUT$) へのハンドルを作成することもできます。 呼び出し元のプロセスは、継承されたコンソールにアタッチするか、AllocConsole 関数によって割り当てられている必要があります。 コンソール ハンドルの場合は、次のように CreateFile2 パラメーターを設定します。| パラメーター | 価値 |
|---|---|
| lpFileName |
CONIN$ 値を使用してコンソール入力を指定します。
CONOUT$ 値を使用してコンソール出力を指定します。 CONIN$ は、SetStdHandle 関数が標準入力ハンドルをリダイレクトした場合でも、コンソール入力バッファーへのハンドルを取得します。 標準入力ハンドルを取得するには、GetStdHandle 関数を使用します。 CONOUT$ は、SetStdHandle が標準出力ハンドルをリダイレクト |
|
dwDesiredAccess を |
GENERIC_READ | GENERIC_WRITE をお勧めしますが、どちらか一方がアクセスを制限できます。
|
|
dwShareMode を |
CONIN$ を開くときに、FILE_SHARE_READを指定します。 CONOUT$ を開く場合は、FILE_SHARE_WRITEを指定します。
呼び出し元のプロセスがコンソールを継承する場合、または子プロセスがコンソールにアクセスできる必要がある場合は、このパラメーターを |
|
dwCreationDisposition の |
CreateFile2 を使用してコンソールを開く場合 |
pCreateExParams パラメーターで渡される CREATEFILE2_EXTENDED_PARAMETERS 構造体のメンバーを次のように設定します。
| メンバーズ | 価値 |
|---|---|
|
lpSecurityAttributes を |
本体を継承する場合は、 |
|
dwFileAttributes を dwFileFlags の dwSecurityQosFlags の hTemplateFile の |
無視。 |
次の表に、
| lpFileName | dwDesiredAccess を |
結果 |
|---|---|---|
| "CON" | GENERIC_READ | 入力用のコンソールを開きます。 |
| "CON" | GENERIC_WRITE | 出力用のコンソールを開きます。 |
| "CON" | GENERIC_READ | GENERIC_WRITE |
CreateFile2 |
Mailslots
createFile2詳細については、「Mailslots」を参照してください。
パイプ
CreateFile2この操作の前に
アクティブなパイプ インスタンスが少なくとも 1 つ存在するが、サーバー上に使用可能なリスナー パイプがない場合、つまり、すべてのパイプ インスタンスが現在接続されていることを意味 、CreateFile2 は ERROR_PIPE_BUSYで失敗します。
詳細については、「パイプ」を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows 8 [デスクトップ アプリ |UWP アプリ] |
| サポートされる最小サーバー | Windows Server 2012 [デスクトップ アプリ |UWP アプリ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | fileapi.h (Windows.h を含む) |
| ライブラリ | Kernel32.lib |
| DLL | Kernel32.dll |
関連項目
ディレクトリ管理 について
ボリューム管理 の
CloseHandle の
CreateDirectory の
CreateDirectoryEx の
CreateFile の
CreateFileTransacted の
CreateMailSlot の
CreateNamedPipe の
ファイル の作成、削除、および保守
DeleteFile の
DeviceIoControl の
Functions
GetLastError の
の概要に関するトピック
ReadFile の
ReadFileEx の
SetFileAttributes の
WriteFile の
WriteFileEx の