次の方法で共有

CreateFileFromAppW 関数 (fileapifromapp.h)

  • [アーティクル]

ファイルまたは 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 Encryption」を参照してください。

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

アクセスはランダムであることを意図しています。 システムは、ファイル キャッシュを最適化するためのヒントとしてこれを使用できます。

このフラグは、ファイル システムがキャッシュされた I/O と FILE_FLAG_NO_BUFFERINGをサポートしていない場合は影響を与えません。

詳細については、このトピックの「キャッシュ動作」セクションを参照してください。
FILE_FLAG_SESSION_AWARE 0x00800000

ファイルまたはデバイスがセッション認識で開かれています。 このフラグが指定されていない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。 このフラグは、セッション 0 に含まれていない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000

アクセスは、最初から最後まで順番に行われます。 システムは、ファイル キャッシュを最適化するためのヒントとしてこれを使用できます。

このフラグは、読み取りビハインド (逆引きスキャン) を使用する場合は使用しないでください。

このフラグは、ファイル システムがキャッシュされた I/O と 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できます。

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

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

戻り値

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

関数が失敗した場合、戻り値は INVALID_HANDLE_VALUE。 拡張エラー情報を取得するには、GetLastError呼び出します。

必要条件

要件 価値
サポートされる最小クライアント Windows 10 バージョン 1803
ヘッダー fileapifromapp.h