CreateFile2FromAppW 関数 (fileapifromapp.h)

[アーティクル]
08/23/2023

ファイルまたは I/O デバイスを作成または開きます。この関数の動作は CreateFile2 と同じですが、この関数はユニバーサル Windows プラットフォームアプリセキュリティモデルに準拠しています。

構文

WINSTORAGEAPI HANDLE CreateFile2FromAppW(
  LPCWSTR                           lpFileName,
  DWORD                             dwDesiredAccess,
  DWORD                             dwShareMode,
  DWORD                             dwCreationDisposition,
  LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
) noexcept;

パラメーター

lpFileName

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

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

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

前もって "\\?\" を指定せずに MAX_PATH 制限からオプトアウトする方法の詳細については、「ファイル、パス、および名前空間の名前付け」の「パスの最大長の制限」セクションを参照してください。

dwDesiredAccess

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

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

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

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

dwShareMode

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

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

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

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

メモ開いている各ハンドルの共有オプションは、プロセスコンテキストに関係なく、そのハンドルが閉じられるまで有効です。

値	意味
0 0x00000000	他のプロセスが削除、読み取り、または書き込みアクセスを要求した場合に、ファイルまたはデバイスを開かないようにします。ファイルまたはディレクトリへの排他的アクセスは、アプリケーションがファイルへの書き込みアクセス権を持っている場合にのみ付与されます。
FILE_SHARE_DELETE 0x00000004	ファイルまたはデバイスに対する後続のオープン操作を有効にして、削除アクセスを要求します。それ以外の場合、削除アクセスを要求した場合、他のプロセスはファイルまたはデバイスを開くことができません。このフラグが指定されていないが、ファイルまたはデバイスが削除アクセス用に開かれている場合、関数は失敗します。メモ削除アクセスでは、削除操作と名前変更操作の両方が許可されます。
FILE_SHARE_READ 0x00000001	ファイルまたはデバイスに対する後続のオープン操作を有効にして、読み取りアクセスを要求します。それ以外の場合、他のプロセスは、読み取りアクセスを要求する場合、ファイルまたはデバイスを開くことができません。このフラグが指定されていないが、ファイルまたはデバイスが読み取りアクセス用に開かれている場合、関数は失敗します。ファイルまたはディレクトリを開いているが、このフラグが指定されておらず、呼び出し元がファイルまたはディレクトリへの書き込みアクセス権を持っていない場合、関数は失敗します。
FILE_SHARE_WRITE 0x00000002	ファイルまたはデバイスに対する後続のオープン操作を有効にして、書き込みアクセスを要求します。それ以外の場合、書き込みアクセスを要求した場合、他のプロセスはファイルまたはデバイスを開くことができません。このフラグが指定されていないが、ファイルまたはデバイスが書き込みアクセス用に開かれているか、書き込みアクセス権を持つファイルマッピングを持っている場合、関数は失敗します。

dwCreationDisposition

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

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

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

値	意味
CREATE_ALWAYS 2	常に新しいファイルを作成します。指定したファイルが存在し、書き込み可能な場合、関数はファイルを切り捨て、関数は成功し、最後のエラーコードは ERROR_ALREADY_EXISTS (183) に設定されます。指定したファイルが存在せず、有効なパスである場合は、新しいファイルが作成され、関数が成功し、最後のエラーコードが 0 に設定されます。
CREATE_NEW 1	まだ存在しない場合にのみ、新しいファイルを作成します。指定したファイルが存在する場合、関数は失敗し、最後のエラーコードは ERROR_FILE_EXISTS (80) に設定されます。指定したファイルが存在せず、書き込み可能な場所への有効なパスである場合は、新しいファイルが作成されます。
OPEN_ALWAYS 4	常にファイルを開きます。指定したファイルが存在する場合、関数は成功し、最後のエラーコードは ERROR_ALREADY_EXISTS (183) に設定されます。指定したファイルが存在せず、書き込み可能な場所への有効なパスである場合、関数はファイルを作成し、最後のエラーコードを 0 に設定します。
OPEN_EXISTING 3	ファイルまたはデバイスが存在する場合にのみ開きます。指定したファイルまたはデバイスが存在しない場合、関数は失敗し、最後のエラーコードは ERROR_FILE_NOT_FOUND (2) に設定されます。
TRUNCATE_EXISTING 5	ファイルを開き、サイズが 0 バイトになるように切り捨てます(存在する場合のみ)。指定したファイルが存在しない場合、関数は失敗し、最後のエラーコードは ERROR_FILE_NOT_FOUND (2) に設定されます。呼び出し元のプロセスでは、dwDesiredAccess パラメーターの一部としてGENERIC_WRITE ビットが設定されたファイルを開く必要があります。

pCreateExParams

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

戻り値

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

失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。詳細なエラー情報を得るには、GetLastError を呼び出します。

必要条件

要件	値
サポートされている最小のクライアント	Windows 10 バージョン 1803
Header	fileapifromapp.h

次の方法で共有

CreateFile2FromAppW 関数 (fileapifromapp.h)

構文

パラメーター

戻り値

必要条件

フィードバック

その他のリソース