CreateFile3 関数 (fileapi.h)

ファイルまたは I/O デバイスを作成または開きます。 最も一般的に使用される I/O デバイスは、ファイル、ファイル ストリーム、ディレクトリ、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、通信リソース、mailslot、パイプです。 この関数は、ファイルまたはデバイス、および指定されたフラグと属性に応じて、さまざまな種類の I/O のファイルまたはデバイスにアクセスするために使用できるハンドルを返します。

サンドボックス パッケージ アプリから呼び出されると、 CreateFile3 が簡略化されます。 ApplicationData.LocalFolder ディレクトリまたは Package.InstalledLocation ディレクトリ内のファイルまたはディレクトリのみを開くことができます。 名前付きパイプやメールスロットを開いたり、暗号化されたファイル (FILE_ATTRIBUTE_ENCRYPTED) を作成したりすることはできません。

構文

HANDLE CreateFile3(
  LPCWSTR                           lpFileName,
  DWORD                             dwDesiredAccess,
  DWORD                             dwShareMode,
  DWORD                             dwCreationDisposition,
  LPCREATEFILE3_EXTENDED_PARAMETERS pCreateExParams
);

パラメーター

lpFileName

作成または開くファイルまたはデバイスの名前。

特殊なデバイス名については、「 MS-DOS デバイス名の定義」を参照してください。

ファイル ストリームを作成するには、ファイルの名前、コロン、ストリームの名前を指定します。 詳細については、「 ファイル ストリーム」を参照してください。

dwDesiredAccess

ファイルまたはデバイスへの要求されたアクセス。読み取り、書き込み、両方、またはゼロとして要約できます。

最も一般的に使用される値は、 GENERIC_READ、 GENERIC_WRITE、またはその両方 (GENERIC_READ | GENERIC_WRITE) です。 詳細については、「 汎用アクセス権、 ファイル セキュリティとアクセス権、 ファイル アクセス権定数、 およびACCESS_MASK」を参照してください。

このパラメーターが 0 の場合、アプリケーションは、ファイル、ディレクトリ、デバイス属性などの特定のメタデータに対してクエリを実行できます。そのファイルやデバイスにアクセスしなくても、 GENERIC_READ アクセスが拒否された場合でも同様です。

既に開いているハンドルを持つオープン要求で dwShareMode パラメーターで指定された共有モードと競合するアクセス モードを要求することはできません。

詳細については、このトピックの 「解説 」セクションおよび 「ファイルの作成と開く」を参照してください。

dwShareMode

ファイルまたはデバイスの要求された共有モード。読み取り、書き込み、両方、削除、これらすべて、またはなしを指定できます (次の表を参照)。 属性または拡張属性へのアクセス要求は、このフラグの影響を受けません。

このパラメーターが 0 で 、CreateFile3 が成功した場合、ファイルまたはデバイスを共有することはできず、ファイルまたはデバイスへのハンドルが閉じられるまで、もう一度開くことはできません。 詳細については、「解説」を参照してください。

開いているハンドルを持つ既存の要求で指定されているアクセス モードと競合する共有モードを要求することはできません。 CreateFile3 は失敗し、 GetLastError 関数は ERROR_SHARING_VIOLATIONを返します。

別のプロセスがファイルまたはデバイスを開いている間にプロセスでファイルまたはデバイスを共有できるようにするには、次の値の 1 つ以上の互換性のある組み合わせを使用します。 このパラメーターと dwDesiredAccess パラメーターの有効な組み合わせの詳細については、「 ファイルの作成と開く」を参照してください。

dwCreationDisposition

存在する、または存在しないファイルまたはデバイスに対して実行するアクション。

ファイル以外のデバイスの場合、通常、このパラメーターは OPEN_EXISTING に設定されます。

詳細については、「解説」を参照してください。

このパラメーターは、組み合わせることができない次のいずれかの値である必要があります。

pCreateExParams

省略可能な CREATEFILE3_EXTENDED_PARAMETERS 構造体へのポインター。

戻り値

関数が成功した場合、戻り値は、指定されたファイル、デバイス、名前付きパイプ、またはメール スロットへの開いているハンドルです。

関数が失敗した場合、戻り値は INVALID_HANDLE_VALUE。 拡張エラー情報を取得するには、GetLastError呼び出します。 考えられるエラーは次のとおりです。

注釈

CreateFile3 は、1 つの例外を除き、 CreateFile2 とまったく同じように動作します。 lpFileName が再解析ポイントまたはシンボリック リンクを介してリダイレクトされた場合、操作は失敗します。 この動作は、 dwFileFlags に追加できる新しいフラグを使用して無効にすることができます。

CreateFile3 関数を使用するアプリケーションをコンパイルするには、_WIN32_WINNT マクロを 0x0602 以降として定義します。 詳細については、「Windows ヘッダーの使用」を参照してください。

CreateFile3 では、Windows 開発者が使用できるファイル操作やその他のほとんどの種類の I/O デバイスとメカニズムがサポートされています。 このセクションでは、さまざまなコンテキストやさまざまな I/O の種類で CreateFile3 を 使用する場合に開発者が経験する可能性があるさまざまな問題について説明します。 テキストは、ファイル システム上の実際の ファイル に格納されているデータを特に参照する場合にのみ、ワード ファイルの使用を試みます。 ただし、ファイルの一部の使用は、 ファイル のようなメカニズムをサポートする I/O オブジェクトをより一般的に参照している可能性があります。 この用語 ファイル のリベラルな使用は、前述の歴史的な理由から、定数名とパラメーター名で特に一般的です。

CreateFile3 によって返されるオブジェクト ハンドルを使用してアプリケーションが終了したら、CloseHandle 関数を使用してハンドルを閉じます。 これにより、システム リソースが解放されるだけでなく、ファイルやデバイスの共有やディスクへのデータのコミットなどに大きな影響を与える可能性があります。 詳細については、このトピック内で適宜説明します。

NTFS ファイル システムなどの一部のファイル システムでは、個々のファイルとディレクトリの圧縮または暗号化がサポートされています。 このサポートを持つマウントされたファイル システムを持つボリュームでは、新しいファイルは、そのディレクトリの圧縮属性と暗号化属性を継承します。

CreateFile3 を使用して、ファイルまたはディレクトリの圧縮、展開、または復号化を制御することはできません。 詳細については、「 ファイルの作成と開き、 ファイルの圧縮と圧縮解除、および ファイル暗号化」を参照してください。

pCreateExParams パラメーターで渡されるCREATEFILE3_EXTENDED_PARAMETERS構造体の lpSecurityAttributes メンバーがNULL場合、CreateFile3 によって返されるハンドルは、アプリケーションで作成できる子プロセスによって継承できません。 このメンバーに関する次の情報も適用されます。

• bInheritHandle メンバー変数が 0 以外の値であるFALSEされていない場合は、ハンドルを継承できます。 そのため、ハンドルを継承可能にしない場合は、この構造体メンバーを FALSE に適切に初期化することが重要です。
• ファイルまたはディレクトリの既定のセキュリティ記述子のアクセス制御リスト (ACL) は、親ディレクトリから継承されます。
• ターゲット ファイル システムは、 lpSecurityDescriptor メンバーがそれらに影響を与えるために、ファイルとディレクトリのセキュリティをサポートする必要があります。これは 、GetVolumeInformation を使用して決定できます。

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジでサポートされています。

シンボリック リンクの動作

この関数の呼び出しによってファイルが作成された場合、動作に変更はありません。 また、pCreateExParams パラメーターで渡されるCREATEFILE3_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 または DeleteFile2 の以前の呼び出しの結果として削除が保留中のファイルに対して CreateFile3 を呼び出すと、関数は失敗します。 オペレーティング システムは、ファイルに対するすべてのハンドルが閉じられるまで、ファイルの削除を遅延します。 GetLastError はERROR_ACCESS_DENIEDを返します。

dwDesiredAccess パラメーターは 0 にすることができ、アプリケーションが適切なセキュリティ設定で実行されている場合、アプリケーションはファイルにアクセスせずにファイル属性を照会できます。 これは、読み取り/書き込みアクセスのためにファイルを開かずにファイルの存在をテストしたり、ファイルまたはディレクトリに関するその他の統計情報を取得したりする場合に便利です。 「ファイル情報の取得と設定」と「GetFileInformationByHandle」を参照してください。

アプリケーションがネットワーク経由でファイルを作成する場合は、GENERIC_WRITEのみを使用するよりも dwDesiredAccess のGENERIC_READ | GENERIC_WRITEを使用することをお勧めします。 リダイレクターはキャッシュ マネージャーを使用でき、送信するデータの数が少ない SMB を減らすことができるため、結果のコードは高速になります。 この組み合わせにより、ネットワーク経由でファイルに書き込むときにERROR_ACCESS_DENIEDが返される場合がある問題も回避 できます。

詳細については、「ファイルの作成と開く」を参照してください。

ファイル ストリーム

NTFS ファイル システムでは、 CreateFile3 を使用してファイル内に個別のストリームを作成できます。 詳細については、「 ファイル ストリーム」を参照してください。

ディレクトリ

アプリケーションは CreateFile3 を使用してディレクトリを作成できないため、このユース ケースでは 、OPEN_EXISTING 値のみが dwCreationDisposition に対して有効です。 ディレクトリを作成するには、アプリケーションで CreateDirectory、CreateDirectoryEx、または CreateDirectory2 を呼び出す必要があります。

CreateFile3 を使用してディレクトリを開くには、pCreateExParams パラメーターで渡されるCREATEFILE3_EXTENDED_PARAMETERS構造体の dwFileFlags メンバーの一部として、FILE_FLAG_BACKUP_SEMANTICS フラグを指定します。 このフラグが SE_BACKUP_NAME および SE_RESTORE_NAME 特権なしで使用されている場合は、適切なセキュリティ チェックが引き続き適用されます。

FAT または FAT32 ファイル システム ボリュームの最適化中に CreateFile3 を使用してディレクトリを開く場合は、 MAXIMUM_ALLOWED アクセス権を指定しないでください。 この操作を行うと、ディレクトリへのアクセスが拒否されます。 代わりに 、GENERIC_READ アクセス権を指定します。

詳細については、「 ディレクトリ管理について」を参照してください。

物理ディスクとボリューム

ディスクまたはボリュームへの直接アクセスは制限されます。

CreateFile3 関数を使用すると、物理ディスク ドライブまたはボリュームを開くことができます。このボリュームは、DeviceIoControl 関数で使用できる直接アクセス ストレージ デバイス (BLOB) ハンドルを返します。 これにより、パーティション テーブルなどのディスク メタデータなど、ディスクまたはボリュームに直接アクセスできます。 ただし、この種類のアクセスでは、ディスク ドライブまたはボリュームのデータ損失の可能性もあります。このメカニズムを使用したディスクへの書き込みが正しくないと、その内容がオペレーティング システムからアクセスできなくなる可能性があるためです。 データの整合性を確保するには、 DeviceIoControl と、ファイル システム ハンドルではなく直接アクセス ハンドルを使用して他の API の動作が異なる方法を理解していることを確認してください。

このような呼び出しを成功させるには、次の要件を満たす必要があります。

• 呼び出し元には管理者特権が必要です。 詳細については、「特別な特権を使用した実行 」を参照してください。
• dwCreationDisposition パラメーターには、OPEN_EXISTING フラグが必要です。
• ボリュームまたはフロッピー ディスクを開く場合、 dwShareMode パラメーターには FILE_SHARE_WRITE フラグが必要です。

物理ドライブ x: を開くと、 lpFileName 文字列は "\.\PhysicalDriveX" の形式になります。

ハード ディスク番号は 0 から始まります。 次の表に、物理ドライブ文字列の例をいくつか示します。

ボリュームの物理ドライブ識別子を取得するには、ボリュームのハンドルを開き、IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTSを使用して DeviceIoControl 関数を呼び出します。 この制御コードは、ボリュームの 1 つ以上のエクステントごとにディスク番号とオフセットを返します。ボリュームは複数の物理ディスクにまたがる場合があります。

物理ドライブを開く例については、「 DeviceIoControl の呼び出し」を参照してください。

ボリュームまたはリムーバブル メディア ドライブ (フロッピー ディスク ドライブやフラッシュ メモリサム ドライブなど) を開く場合、 lpFileName 文字列は "\\.\X:" という形式にする必要があります。 ドライブのルート ディレクトリを示す末尾の円記号 (\) は使用しないでください。

ドライブ文字列の例を次の表に示します。

ボリューム名を参照してボリュームを開くこともできます。 詳細については、「 ボリュームの名前付け」を参照してください。

ボリュームには、1 つ以上のマウントされたファイル システムが含まれています。 ボリューム ハンドルは、 CreateFile3 でキャッシュされていないオプションが指定されていない場合でも、特定のファイル システムの判断でキャッシュされていないものとして開くことができます。 すべての Microsoft ファイル システムがボリューム ハンドルをキャッシュされていないものとして開くと想定する必要があります。 ファイルのキャッシュされていない I/O に対する制限もボリュームに適用されます。

ファイル システムでは、データがキャッシュされていない場合でも、バッファーの配置が必要な場合と必要ない場合があります。 ただし、ボリュームを開くときにキャッシュされていないオプションが指定されている場合は、ボリューム上のファイル システムに関係なく、バッファーの配置が適用されます。 ボリューム ハンドルをキャッシュなしとして開き、キャッシュされていない I/O 制限に従うすべてのファイル システムで推奨されます。

チェンジャー デバイス

DeviceIoControl の IOCTL_CHANGER_* コントロール コードは、チェンジャー デバイスへのハンドルを受け入れます。 チェンジャー デバイスを開くには、"\.\Changerx" という形式のファイル名を使用します。 ここで、x は、開くデバイスを示す数値で、ゼロから始まります。 C または C++ で記述されたアプリケーションで changer デバイス 0 を開くには、"\\.\Changer0" というファイル名を使用します。

テープ ドライブ

テープ ドライブを開くには、"\.\TAPEx" という形式のファイル名を使用します。 ここで、x は、テープ ドライブ 0 から始まる、開くドライブを示す番号です。 C または C++ で記述されたアプリケーションでテープ ドライブ 0 を開くには、"\\.\TAPE0" というファイル名を使用します。

詳細については、「バックアップ」を参照してください。

通信リソース

CreateFile3 関数は、シリアル ポート COM1 などの通信リソースへのハンドルを作成できます。 通信リソースの場合、 dwCreationDisposition パラメーターは OPEN_EXISTINGする必要があります。 dwShareMode パラメーターは 0 (排他アクセス) にする必要があり、 hTemplateFile パラメーターは NULLする必要があります。 読み取り、書き込み、または読み取り/書き込みアクセスを指定でき、重複する I/O に対してハンドルを開くことができます。

9 より大きい COM ポート番号を指定するには、"\.\COM10" という構文を使用します。 この構文は、COM ポート番号を指定できるすべてのポート番号とハードウェアに対して機能します。

通信の詳細については、「 通信」を参照してください。

コンソール

CreateFile3 関数は、コンソール入力 (CONIN$) へのハンドルを作成できます。 継承または重複の結果としてプロセスに開いているハンドルがある場合は、アクティブな画面バッファー (CONOUT$) へのハンドルを作成することもできます。 呼び出し元のプロセスは、継承されたコンソールまたは AllocConsole 関数によって割り当てられたコンソールにアタッチされている必要があります。

コンソール ハンドルの場合は、 CreateFile3 パラメーターを次のように設定します。

pCreateExParams パラメーターで渡されるCREATEFILE3_EXTENDED_PARAMETERS構造体のメンバーを次のように設定します。

次の表は、 dwDesiredAccess と lpFileName のさまざまな設定を示しています。

Mailslots

CreateFile3 が mailslot のクライアント側を開いた場合、mailslot サーバーが CreateMailSlot 関数を使用して作成する前に、mailslot クライアントがローカル mailslot を開こうとした場合、この関数はINVALID_HANDLE_VALUEを返します。

詳細については、「Mailslots」を参照してください。

パイプ

CreateFile3 が名前付きパイプのクライアント側を開いた場合、関数はリッスン状態にある名前付きパイプのインスタンスを使用します。 開始プロセスは必要な回数ハンドルを複製できますが、開いた後、名前付きパイプ インスタンスを別のクライアントが開くことはできません。 パイプを開くときに指定するアクセスは、CreateNamedPipe 関数の dwOpenMode パラメーターで指定されたアクセスと互換性がある必要があります。

この操作の前 にサーバーで CreateNamedPipe 関数が正常に呼び出されなかった場合、パイプは存在せず、 CreateFile3 は ERROR_FILE_NOT_FOUNDで失敗します。

アクティブなパイプ インスタンスが少なくとも 1 つ存在するが、サーバー上に使用可能なリスナー パイプがない場合(つまり、すべてのパイプ インスタンスが現在接続されていることを意味します)、 CreateFile3 は ERROR_PIPE_BUSYで失敗します。

詳細については、「パイプ」を参照してください。

必要条件

こちらもご覧ください

CreateDirectory2

DeleteFile2

RemoveDirectory2