CreateFileFromAppW 関数 (fileapifromapp.h)

[アーティクル]
03/09/2023

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

構文

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

パラメーター

lpFileName

作成または開くファイルまたはデバイスの名前。この名前にはスラッシュ (/) または円記号 (\) を使用できます。

この関数の ANSI バージョンでは、名前は MAX_PATH 文字に制限されています。この制限を 32,767 文字のワイド文字に拡張するには、Unicode バージョンの関数を呼び出し、パスの先頭に "\\?\" を付加します。詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

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

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

この関数の Unicode バージョン (CreateFileFromAppW) の場合は、"\\?\" を前に置かずに 、MAX_PATH の制限を削除するようにオプトインできます。詳細については、「ファイル、パス、および名前空間の名前付け」の「最大パス長の制限」セクションを参照してください。

dwDesiredAccess

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

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

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

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

dwShareMode

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

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

lpSecurityAttributes

2 つの個別の関連データメンバーを含む SECURITY_ATTRIBUTES 構造体へのポインター。省略可能なセキュリティ記述子と、返されたハンドルを子プロセスで継承できるかどうかを決定するブール値。

このパラメーターは、NULL でもかまいません。

このパラメーターが NULL の場合、返されるハンドルは、アプリケーションが作成できる子プロセスで継承できず、返されたハンドルに関連付けられているファイルまたはデバイスは既定のセキュリティ記述子を取得します。

構造体の lpSecurityDescriptor メンバーは、ファイルまたはデバイスの SECURITY_DESCRIPTOR を指定します。このメンバーが NULL の場合、返されたハンドルに関連付けられているファイルまたはデバイスには、既定のセキュリティ記述子が割り当てられます。

この関数は、既存のファイルまたはデバイスを開くときに lpSecurityDescriptor メンバーを無視しますが、引き続き bInheritHandle メンバーを使用します。

構造体の bInheritHandle メンバーは、返されたハンドルを継承できるかどうかを指定します。

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 ビットが設定されたファイルを開く必要があります。

dwFlagsAndAttributes

ファイルまたはデバイスの属性とフラグ FILE_ATTRIBUTE_NORMAL 、ファイルの最も一般的な既定値です。

このパラメーターには、使用可能なファイル属性 (FILE_ATTRIBUTE_*) の任意の組み合わせを含めることができます。その他のすべてのファイル属性は、 FILE_ATTRIBUTE_NORMALをオーバーライドします。

このパラメーターには、ファイルまたはデバイスのキャッシュ動作、アクセスモード、およびその他の特殊な目的のフラグを制御するためのフラグ (FILE_FLAG_*) の組み合わせを含めることもできます。これらは、任意のFILE_ATTRIBUTE_* 値と組み合わされます。

このパラメーターには、 SECURITY_SQOS_PRESENT フラグを指定することで、サービス品質 (SQOS) 情報を含めることもできます。その他の SQOS 関連のフラグ情報は、属性テーブルとフラグテーブルの後の表に示されています。

属性	説明
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	ファイルをアーカイブする必要があります。アプリケーションでは、この属性を使用して、バックアップまたは削除の対象にファイルをマークします。
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	ファイルまたはディレクトリは暗号化されています。ファイルの場合は、ファイルのすべてのデータが暗号化されています。ディレクトリの場合、新しく作成されたファイルとサブディレクトリの既定値は暗号化であることを意味します。詳細については、「ファイルの暗号化」を参照してください。 FILE_ATTRIBUTE_SYSTEMも指定されている場合、このフラグは無効です。このフラグは、Windows の Home、Home Premium、Starter、または ARM エディションではサポートされていません。
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	ファイルが非表示になっています。通常のディレクトリ一覧には含めないでください。
FILE_ATTRIBUTE_NORMAL 128 (0x80)	ファイルには他の属性が設定されていません。この属性は、単独で使用された場合にのみ有効です。
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	ファイルのデータはすぐには使用できません。この属性は、ファイルデータが物理的にオフラインストレージに移動されることを示します。この属性は、階層型ストレージ管理ソフトウェアであるリモートストレージによって使用されます。アプリケーションはこの属性を任意に変更しないでください。
FILE_ATTRIBUTE_READONLY 1 (0x1)	ファイルは読み取り専用です。アプリケーションはファイルを読み取ることができますが、書き込んだり削除したりすることはできません。
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	ファイルは、オペレーティングシステムの一部であるか、オペレーティングシステムによって排他的に使用されます。
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	ファイルは一時ストレージに使用されています。詳細については、このトピックの「キャッシュ動作」セクションを参照してください。

フラグ	説明
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	バックアップまたは復元操作のためにファイルが開かれているか作成されています。システムは、プロセスに SE_BACKUP_NAME と SE_RESTORE_NAME の特権がある場合に、呼び出し元のプロセスがファイルセキュリティチェックをオーバーライドすることを保証します。詳細については、「トークンでの特権の変更」を参照してください。ディレクトリへのハンドルを取得するには、このフラグを設定する必要があります。ディレクトリハンドルは、ファイルハンドルではなく一部の関数に渡すことができます。詳細については、「解説」を参照してください。
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	そのハンドルがすべて閉じられた直後にファイルは削除されることになります。このハンドルには、指定されたハンドルと、他の開いているハンドルまたは重複した他のハンドルが含まれます。ファイルに対して開いているハンドルが存在する場合、 FILE_SHARE_DELETE 共有モードですべて開かなければ、呼び出しは失敗します。 FILE_SHARE_DELETE 共有モードが指定されていない限り、ファイルに対する後続のオープン要求は失敗します。
FILE_FLAG_NO_BUFFERING 0x20000000	ファイルまたはデバイスは、データの読み取りと書き込みのシステムキャッシュなしで開かれています。このフラグは、ハードディスクキャッシュやメモリマップファイルには影響しません。 FILE_FLAG_NO_BUFFERING フラグを使用してこの関数で開かれたファイルを正常に操作するには、厳密な要件があります。詳細については、「ファイルバッファリング」を参照してください。
FILE_FLAG_OPEN_NO_RECALL 0x00100000	ファイルデータは要求されますが、引き続きリモートストレージに配置する必要があります。ローカルストレージに転送しないでください。このフラグは、リモート・ストレージ・システムで使用されます。
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	通常の再解析ポイント処理は行われません。この関数は、再解析ポイントを開こうとします。ファイルを開くと、再解析ポイントを制御するフィルターが動作可能かどうかに関係なく、ファイルハンドルが返されます。このフラグは、CREATE_ALWAYS フラグでは使用できません。ファイルが再解析ポイントでない場合、このフラグは無視されます。詳細については、「解説」を参照してください。
FILE_FLAG_OVERLAPPED 0x40000000	ファイルまたはデバイスは、非同期 I/O 用に開かれているか作成されています。このハンドルで後続の I/O 操作が完了すると、 OVERLAPPED 構造体で指定されたイベントがシグナル状態に設定されます。このフラグを指定すると、読み取りと書き込みの同時操作にファイルを使用できます。このフラグが指定されていない場合、読み取りおよび書き込み関数の呼び出しで OVERLAPPED 構造体が指定されている場合でも、I/O 操作はシリアル化されます。このフラグで作成されたファイルハンドルを使用する場合の考慮事項については、このトピックの「同期および非同期 I/O ハンドル」セクションを参照してください。
FILE_FLAG_POSIX_SEMANTICS 0x0100000	アクセスは POSIX ルールに従って行われます。これには、その名前付けをサポートするファイルシステムに対して、名前が異なる複数のファイルを許可することが含まれます。 MS-DOS または 16 ビット Windows 用に作成されたアプリケーションでは、このフラグで作成されたファイルにアクセスできない可能性があるため、このオプションを使用する場合は注意が必要です。
FILE_FLAG_RANDOM_ACCESS 0x10000000	アクセスはランダムであることを意図しています。システムはこれをヒントとしてファイルのキャッシュを最適化します。ファイル・システムがキャッシュ入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。詳細については、このトピックの「キャッシュ動作」セクションを参照してください。
FILE_FLAG_SESSION_AWARE 0x00800000	ファイルまたはデバイスがセッション認識で開かれています。このフラグを指定しない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。このフラグは、セッション 0 に含まれていない呼び出し元には影響しません。このフラグは、Windows のサーバーエディションでのみサポートされます。
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	アクセスは、最初から最後まで順番に行われるよう意図されています。システムはこれをヒントとしてファイルのキャッシュを最適化します。このフラグは、読み取りビハインド (つまり、逆スキャン) を使用する場合は使用しないでください。ファイル・システムがキャッシュ入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。詳細については、このトピックの「キャッシュ動作」セクションを参照してください。
FILE_FLAG_WRITE_THROUGH 0x80000000	書き込み操作は中間キャッシュを通過せず、ディスクに直接移動します。詳細については、このトピックの「キャッシュ動作」セクションを参照してください。

dwFlagsAndAttributesパラメーターでは、SQOS 情報を指定することもできます。詳細については、「偽装レベル」を参照してください。呼び出し元のアプリケーションが dwFlagsAndAttributes の一部として SECURITY_SQOS_PRESENT フラグを指定する場合は、次の値の 1 つ以上を含めることもできます。

セキュリティフラグ	意味
SECURITY_ANONYMOUS	匿名偽装レベルでクライアントを偽装します。
SECURITY_CONTEXT_TRACKING	セキュリティ追跡モードは動的です。このフラグを指定しない場合、セキュリティ追跡モードは静的です。
SECURITY_DELEGATION	委任偽装レベルでクライアントを偽装します。
SECURITY_EFFECTIVE_ONLY	サーバーで使用できるのは、クライアントのセキュリティコンテキストの有効な側面のみです。このフラグを指定しない場合は、クライアントのセキュリティコンテキストのすべての側面を使用できます。これにより、クライアントは、クライアントの偽装中にサーバーが使用できるグループと特権を制限できます。
SECURITY_IDENTIFICATION	Id 偽装レベルでクライアントを偽装します。
SECURITY_IMPERSONATION	偽装レベルでクライアントを偽装する。これは、 SECURITY_SQOS_PRESENT フラグと共に他のフラグが指定されていない場合の既定の動作です。

hTemplateFile

GENERIC_READアクセス権を持つテンプレートファイルへの有効なハンドル。テンプレートファイルは、作成するファイルにファイル属性と拡張属性を提供します。

このパラメーターは、NULL でもかまいません。

既存のファイルを開くとき、このパラメーターは無視されます。

新しい暗号化されたファイルを開くと、ファイルは親ディレクトリから随意アクセス制御リストを継承します。詳細については、「ファイルの暗号化」を参照してください。

戻り値

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

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

必要条件


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

次の方法で共有

CreateFileFromAppW 関数 (fileapifromapp.h)

構文

パラメーター

戻り値

必要条件

フィードバック

その他のリソース