CreateFileTransactedW 関数 (winbase.h)
[Microsoft では、開発者がアプリケーションのニーズを達成するために代替手段を利用することを強くお勧めします。 TxF が開発された多くのシナリオは、よりシンプルで利用しやすい手法で実現できます。 また、将来のバージョンの Microsoft Windows では TxF を使用できない場合があります。 詳細、および TxF の代替手段については、「トランザクション NTFS の使用の代替手段」を参照してください。]
トランザクション操作として、ファイル、ファイル ストリーム、またはディレクトリを作成するか、開きます。 関数は、オブジェクトへのアクセスに使用できるハンドルを返します。
この操作を非変換操作として実行するか、ファイル以外のオブジェクト (名前付きパイプ、物理デバイス、mailslots など) にアクセスするには、 CreateFile 関数を使用します。
トランザクションの詳細については、このトピックの「解説」セクションを参照してください。
構文
HANDLE CreateFileTransactedW(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile,
[in] HANDLE hTransaction,
[in, optional] PUSHORT pusMiniVersion,
PVOID lpExtendedParameter
);
パラメーター
[in] lpFileName
作成するか、または開くオブジェクトの名前。
オブジェクトはローカル コンピューター上に存在する必要があります。それ以外の場合、関数は失敗し、最後のエラー コードは ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE に設定されます。
既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。
ヒント
Windows 10 バージョン 1607 以降では、"\\?\" を前に置かずに、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 ファイル、パス、および名前空間の名前付け 」の「最大パス長の制限」セクションを参照してください。
ファイル ストリームを作成するには、ファイルの名前、コロン、ストリームの名前を指定します。 詳細については、「 ファイル ストリーム」を参照してください。
[in] dwDesiredAccess
オブジェクトへのアクセス。読み取り、書き込み、両方またはどちらも (ゼロ) として要約できます。 最も一般的に使用される値は、GENERIC_READ、GENERIC_WRITE、またはその両方 (GENERIC_READ GENERIC_WRITE | ) です。 詳細については、「 汎用アクセス権 」および「 ファイル セキュリティとアクセス権」を参照してください。
このパラメーターが 0 の場合、アプリケーションはそのファイルまたはデバイスにアクセスすることなく、ファイル、ディレクトリ、またはデバイスの属性に対してクエリを実行できます。 詳細については、このトピックの「解説」セクションを参照してください。
開いているハンドルを持つオープン要求で指定された共有モードと競合するアクセス・モードを要求することはできません。 詳細については、「ファイルの作成とオープン」を参照してください。
[in] dwShareMode
オブジェクトの共有モード。読み取り、書き込み、両方、削除、これらすべて、またはなしを指定できます (次の表を参照)。
このパラメーターが 0 で CreateFileTransacted が成功した 場合、オブジェクトは共有できず、ハンドルが閉じられるまでもう一度開くことはできません。 詳細については、このトピックの「解説」セクションを参照してください。
開いているハンドルを持つオープン要求で指定されたアクセス モードと競合する共有モードを要求することはできません。その結果、共有違反が発生します: ERROR_SHARING_VIOLATION。 詳細については、「ファイルの作成とオープン」を参照してください。
別のプロセスがオブジェクトを開いている間にプロセスでオブジェクトを共有できるようにするには、次の値の 1 つ以上を組み合わせて、オブジェクトを開くために要求できるアクセス モードを指定します。
[in, optional] lpSecurityAttributes
オプションのセキュリティ記述子を含み、返されたハンドルを子プロセスによって継承できるかどうかを決定する、SECURITY_ATTRIBUTES構造体へのポインター。 パラメーターには NULL を指定できます。
lpSecurityAttributes パラメーターが NULL の場合、CreateFileTransacted によって返されるハンドルは、アプリケーションで作成できる子プロセスで継承できず、返されたハンドルに関連付けられているオブジェクトは既定のセキュリティ記述子を取得します。
構造体の bInheritHandle メンバーは、返されたハンドルを継承できるかどうかを指定します。
構造体の lpSecurityDescriptor メンバーは、オブジェクトの セキュリティ記述子 を指定しますが、 NULL にすることもできます。
lpSecurityDescriptor メンバーが NULL の場合、返されるハンドルに関連付けられているオブジェクトには、既定のセキュリティ記述子が割り当てられます。
CreateFileTransacted は 、既存のファイルを開くときに lpSecurityDescriptor メンバーを無視しますが、引き続き bInheritHandle メンバーを使用します。
詳細については、このトピックの「解説」セクションを参照してください。
[in] dwCreationDisposition
存在するファイルと存在しないファイルに対して実行するアクション。
詳細については、このトピックの「解説」セクションを参照してください。
このパラメーターは、組み合わせることができない次のいずれかの値である必要があります。
[in] dwFlagsAndAttributes
ファイルの属性とフラグ FILE_ATTRIBUTE_NORMAL 最も一般的な既定値です。
このパラメーターには、使用可能なファイル属性 (FILE_ATTRIBUTE_*) の任意の組み合わせを含めることができます。 その他のすべてのファイル属性は、 FILE_ATTRIBUTE_NORMALをオーバーライドします。
このパラメーターには、バッファリング動作、アクセス モード、およびその他の特殊な目的のフラグを制御するためのフラグ (FILE_FLAG_) の組み合わせを含めることもできます。 これらは、任意 のFILE_ATTRIBUTE_ 値と組み合わされます。
このパラメーターには、 SECURITY_SQOS_PRESENT フラグを指定することで、サービス品質 (SQOS) 情報を含めることもできます。 その他の SQOS 関連のフラグ情報は、属性テーブルとフラグ テーブルの後の表に示されています。
CreateFileTransacted によって既存のファイルが開かれると、通常、ファイル フラグと既存のファイルのファイル属性が結合され、dwFlagsAndAttributes の一部として指定されたファイル属性は無視されます。 特殊なケースについては、「 ファイルの作成と開き方」を参照してください。
| 属性 | 説明 |
|---|---|
|
ファイルをアーカイブする必要があります。 アプリケーションでは、この属性を使用して、バックアップまたは削除の対象にファイルをマークします。 |
|
ファイルまたはディレクトリは暗号化されています。 ファイルの場合は、ファイルのすべてのデータが暗号化されています。 ディレクトリの場合、新しく作成されたファイルとサブディレクトリの既定値は暗号化であることを意味します。 詳細については、「 ファイルの暗号化」を参照してください。
FILE_ATTRIBUTE_SYSTEMも指定されている場合、このフラグは無効です。 |
|
ファイルが非表示になっています。 通常のディレクトリ一覧には含めないでください。 |
|
ファイルには他の属性が設定されていません。 この属性は、単独で使用された場合にのみ有効です。 |
|
ファイルのデータはすぐには使用できません。 この属性は、ファイル データが物理的にオフライン ストレージに移動されることを示します。 この属性は、階層型ストレージ管理ソフトウェアであるリモート ストレージによって使用されます。 アプリケーションはこの属性を任意に変更しないでください。 |
|
ファイルは読み取り専用です。 アプリケーションはファイルを読み取ることができますが、書き込んだり削除したりすることはできません。 |
|
ファイルは、オペレーティング システムの一部であるか、オペレーティング システムによって排他的に使用されます。 |
|
ファイルは一時ストレージに使用されています。 ハンドルが閉じられた後にアプリケーションによって一時ファイルが削除されるため、十分なキャッシュ メモリが使用可能な場合、ファイル システムは大容量ストレージにデータを書き戻すのを避けます。 その場合、システムはデータの書き込みを完全に回避できます。 それ以外の場合は、ハンドルが閉じられた後にデータが書き込まれます。 |
| フラグ | 説明 |
|---|---|
|
バックアップまたは復元操作のためにファイルが開かれているか作成されています。 システムは、プロセスに SE_BACKUP_NAME と SE_RESTORE_NAME の特権がある場合に、呼び出し元のプロセスがファイル セキュリティ チェックをオーバーライドすることを保証します。 詳細については、「 トークンでの特権の変更」を参照してください。
ディレクトリへのハンドルを取得するには、このフラグを設定する必要があります。 ディレクトリ ハンドルは、ファイル ハンドルではなく一部の関数に渡すことができます。 詳細については、「 ディレクトリ ハンドル」を参照してください。 |
|
トランザクションがまだアクティブである場合、ファイルに対する最後のトランザクション ライター ハンドルが閉じられた直後に、ファイルが削除されます。 ファイルが削除対象としてマークされていて、トランザクションの完了後もトランザクション ライター ハンドルが開いている場合、ファイルは削除されません。
ファイルに対して開いているハンドルが存在する場合、 FILE_SHARE_DELETE 共有モードですべて開かなければ、呼び出しは失敗します。 FILE_SHARE_DELETE 共有モードが指定されていない限り、ファイルに対する後続のオープン要求は失敗します。 |
|
ファイルは、システム キャッシュなしで開かれています。 このフラグは、ハード ディスクキャッシュやメモリマップファイルには影響しません。 FILE_FLAG_OVERLAPPEDと組み合わせると、I/O はメモリ マネージャーの同期操作に依存しないため、 フラグによって最大の非同期パフォーマンスが得られます。
ただし、データがキャッシュに保持されていないため、一部の I/O 操作には時間がかかります。 また、ファイル メタデータは引き続きキャッシュされる可能性があります。 メタデータをディスクにフラッシュするには、FlushFileBuffers 関数を使用します。
アプリケーションは、FILE_FLAG_NO_BUFFERINGで開かれたファイルを操作するときに、特定の要件 を満たす必要があります。
アプリケーションは 、GetDiskFreeSpace 関数を呼び出すことによって、ボリューム セクターのサイズを決定できます。 |
|
ファイル データは要求されますが、引き続きリモート ストレージに配置する必要があります。 ローカル ストレージに転送しないでください。 このフラグは、リモート・ストレージ・システムで使用されます。 |
|
通常 の再解析ポイント 処理は行われません。 CreateFileTransacted は再解析ポイントを開こうとします。 ファイルを開くと、再解析ポイントを制御するフィルターが動作可能かどうかに関係なく、ファイル ハンドルが返されます。 このフラグは 、CREATE_ALWAYS フラグでは使用できません。 ファイルが再解析ポイントでない場合、このフラグは無視されます。 |
|
非同期 I/O 用にファイルが開かれるか、または作成されます。 操作が完了すると、 OVERLAPPED 構造体で指定されたイベントがシグナル状態に設定されます。 処理にかなりの時間がかかる操作は 、ERROR_IO_PENDINGを返します。
このフラグを指定すると、読み取りと書き込みの同時操作にファイルを使用できます。 システムはファイル ポインターを維持しないため、 OVERLAPPED 構造体の読み取りおよび書き込み関数にファイル位置を渡すか、ファイル ポインターを更新する必要があります。 このフラグが指定されていない場合、読み取りおよび書き込み関数の呼び出しで OVERLAPPED 構造体が指定されている場合でも、I/O 操作はシリアル化されます。 |
|
ファイルは POSIX 規則に従ってアクセスされます。 これには、その名前付けをサポートするファイル システムに対して、名前が異なる複数のファイルを許可することが含まれます。 MS-DOS または 16 ビット Windows 用に作成されたアプリケーションでは、このフラグで作成されたファイルにアクセスできない可能性があるため、このオプションを使用する場合は注意が必要です。 |
|
ファイルはランダムにアクセスされます。 システムはこれをヒントとしてファイルのキャッシュを最適化します。 |
|
ファイルまたはデバイスがセッション認識で開かれています。 このフラグを指定しない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。
このフラグは、セッション 0 に含まれていない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。
Windows Server 2008 R2 と Windows Server 2008: このフラグは、Windows Server 2012する前にサポートされていません。 |
|
ファイルは、最初から最後まで順番にアクセスされます。 システムはこれをヒントとしてファイルのキャッシュを最適化します。 アプリケーションがランダム アクセスのためにファイル ポインターを移動すると、最適なキャッシュが発生しない可能性があります。 ただし、正しい操作は引き続き保証されます。
このフラグを指定すると、シーケンシャル アクセスを使用して大きなファイルを読み取るアプリケーションのパフォーマンスが向上する可能性があります。 パフォーマンスの向上は、大きなファイルを主に順次読み取るアプリケーションではさらに顕著になる可能性がありますが、場合によっては小さなバイト範囲をスキップします。 ファイル・システムがキャッシュ入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。 |
|
書き込み操作は中間キャッシュを通過せず、ディスクに直接移動します。
FILE_FLAG_NO_BUFFERINGも指定されていないので、システム キャッシュが有効になっている場合、データはシステム キャッシュに書き込まれますが、ディスクに遅延なくフラッシュされます。 FILE_FLAG_NO_BUFFERINGも指定されているため、システム キャッシュが有効にならない場合、データはシステム キャッシュを経由せずにすぐにディスクにフラッシュされます。 オペレーティング システムは、ハード ディスク キャッシュを通じて永続メディアへの書き込みも要求します。 ただし、すべてのハードウェアがこのライトスルー機能をサポートしているわけではありません。 |
dwFlagsAndAttributes パラメーターでは、セキュリティサービス品質情報を指定することもできます。 詳細については、「 偽装レベル」を参照してください。 呼び出し元のアプリケーションが dwFlagsAndAttributes の一部として SECURITY_SQOS_PRESENT フラグを指定する場合は、次の値の 1 つ以上を含めることもできます。
[in, optional] hTemplateFile
GENERIC_READアクセス権を持つテンプレート ファイルへの有効なハンドル。 テンプレート ファイルは、作成するファイルにファイル属性と拡張属性を提供します。 このパラメーターは、NULL でもかまいません。
既存のファイルを開くと、 CreateFileTransacted はテンプレート ファイルを無視します。
新しい EFS で暗号化されたファイルを開くと、そのファイルは親ディレクトリから DACL を継承します。
[in] hTransaction
トランザクションのハンドル。 このハンドルは、 CreateTransaction 関数によって返されます。
[in, optional] pusMiniVersion
開くミニバージョン。 hTransaction で指定されたトランザクションがファイルを変更しているトランザクションでない場合、このパラメーターは NULL にする必要があります。 それ以外の場合、このパラメーターには、 FSCTL_TXFS_CREATE_MINIVERSION 制御コードによって返されるミニバージョン識別子、または次のいずれかの値を指定できます。
lpExtendedParameter
このパラメーターは予約されており、 NULL である必要があります。
戻り値
関数が成功した場合、戻り値は、指定されたファイル、デバイス、名前付きパイプ、またはメール スロットへのオープン ハンドルです。
失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
CreateFileTransacted によって返されるハンドルを使用する場合は、必要に応じて標準のファイル I/O 関数ではなく、トランザクションバージョンのファイル I/O 関数を使用します。 詳細については、「 トランザクション NTFS のプログラミングに関する考慮事項」を参照してください。
ディレクトリに対してトランザクション ハンドルを開く場合、そのハンドルには FILE_WRITE_DATA (FILE_ADD_FILE) と FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY) のアクセス許可が必要です。 これらは、 FILE_GENERIC_WRITE のアクセス許可に含まれています。 ハンドルを使用してファイルまたはサブディレクトリを作成するだけの場合は、アクセス許可が少ないディレクトリを開く必要があります。そうしないと、共有違反が発生する可能性があります。
そのファイルが別のトランザクションの一部である場合 (つまり、CreateFileTransacted を呼び出して開いた別のアプリケーション)、アクセス レベルFILE_EXECUTEファイルを開くことはできません。 つまり、アクセス レベルがFILE_EXECUTEまたはFILE_ALL_ACCESSが指定されている場合、CreateFileTransacted は失敗します
トランザクションされていないアプリケーションが、lpSecurityAttributes に指定されたMAXIMUM_ALLOWEDで CreateFileTransacted を呼び出すと、毎回同じアクセス レベルでハンドルが開かれます。 トランザクションアプリケーションが lpSecurityAttributes に対して指定されたMAXIMUM_ALLOWEDで CreateFileTransacted を呼び出すと、トランザクションによってファイルがロックされているかどうかに基づいて、異なる量のアクセス権でハンドルが開かれます。 たとえば、呼び出し元のアプリケーションにファイルのアクセス レベル FILE_EXECUTE がある場合、開いているファイルがトランザクションによってロックされていないか、トランザクションによってロックされていて、アプリケーションがそのファイルのトランザクション リーダーである場合にのみ、アプリケーションはこのアクセス権を取得します。
トランザクション操作の詳細については、「 トランザクション NTFS 」を参照してください。
CloseHandle 関数を使用して、ハンドルが不要になったとき、およびトランザクションをコミットまたはロールバックする前に、CreateFileTransacted によって返されるオブジェクト ハンドルを閉じます。
NTFS ファイル システムなどの一部のファイル システムでは、個々のファイルとディレクトリの圧縮または暗号化がサポートされています。 その種類のファイル システム用にフォーマットされたボリュームでは、新しいファイルは、そのディレクトリの圧縮属性と暗号化属性を継承します。
CreateFileTransacted を使用して、ファイルまたはディレクトリの圧縮を制御することはできません。 詳細については、「 ファイルの圧縮と圧縮解除」および「 ファイル暗号化」を参照してください。
シンボリック リンクの動作 — この関数の呼び出しによって新しいファイルが作成された場合、動作に変更はありません。
FILE_FLAG_OPEN_REPARSE_POINTが指定されている場合:
- 既存のファイルが開かれ、それがシンボリック リンクである場合、返されるハンドルはシンボリック リンクへのハンドルです。
- TRUNCATE_EXISTINGまたはFILE_FLAG_DELETE_ON_CLOSEが指定されている場合、影響を受けるファイルはシンボリック リンクです。
- 既存のファイルが開かれ、それがシンボリック リンクである場合、返されるハンドルはターゲットへのハンドルです。
- CREATE_ALWAYS、TRUNCATE_EXISTING、または FILE_FLAG_DELETE_ON_CLOSE が指定されている場合、影響を受けるファイルはターゲットです。
前述のように、 lpSecurityAttributes パラメーターが NULL の場合、 CreateFileTransacted によって返されるハンドルは、アプリケーションで作成できる子プロセスで継承できません。 このパラメーターに関する次の情報も適用されます。
- bInheritHandle が FALSE ではなく、0 以外の値である場合は、ハンドルを継承できます。 したがって、ハンドルを継承可能にする予定がない場合は、この構造体メンバーを FALSE に適切に初期化することが重要です。
- ファイルまたはディレクトリの既定のセキュリティ記述子のアクセス制御リスト (ACL) は、親ディレクトリから継承されます。
- ターゲット ファイル システムは、lpSecurityDescriptor がそれらに影響を与えるためにファイルとディレクトリのセキュリティをサポートする必要があります。これは、GetVolumeInformation を使用して決定できます
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | いいえ |
| SMB 3.0 Transparent Failover (TFO) | いいえ |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | いいえ |
| クラスターの共有ボリューム ファイル システム (CsvFS) | いいえ |
| Resilient File System (ReFS) | いいえ |
SMB 3.0 では TxF がサポートされないことに注意してください。
ファイル
フロッピー ディスクを持たないフロッピー ドライブまたは CD を持たない CD-ROM ドライブにファイルを作成しようとすると、ユーザーがディスクまたは CD を挿入するためのメッセージが表示されます。 システムでこのメッセージが表示されないようにするには、 setErrorMode 関数を SEM_FAILCRITICALERRORSと共に呼び出します。詳細については、「ファイルの作成とオープン」を参照してください。
ファイルの名前を変更または削除した後すぐに復元すると、システムはキャッシュで復元するファイル情報を検索します。 キャッシュされた情報には、短い名前と長い名前のペアと作成時間が含まれます。
DeleteFile の前回の呼び出しの結果として削除が保留中のファイルで CreateFileTransacted を呼び出すと、関数は失敗します。 オペレーティング システムは、ファイルに対するすべてのハンドルが閉じられるまでファイルの削除を遅延します。 GetLastError はERROR_ACCESS_DENIEDを返します。
dwDesiredAccess パラメーターは 0 にすることができ、アプリケーションが適切なセキュリティ設定で実行されている場合、アプリケーションはファイルにアクセスせずにファイル属性のクエリを実行できます。 これは、読み取りアクセスや書き込みアクセスのためにファイルを開かずにファイルの存在をテストしたり、ファイルまたはディレクトリに関するその他の統計情報を取得したりするのに役立ちます。 「ファイル情報の取得と設定」および「GetFileInformationByHandle」を参照してください。
アプリケーションがネットワーク経由でファイルを作成する場合は、GENERIC_WRITEのみを使用するよりも、GENERIC_READ | GENERIC_WRITEを使用することをお勧めします。 リダイレクターはキャッシュ マネージャーを使用し、より多くのデータを含むより少ない SMB を送信できるため、結果のコードは高速になります。 この組み合わせにより、ネットワーク経由でファイルに書き込む際にERROR_ACCESS_DENIEDが返される場合がある問題も回避 できます。
ファイル ストリーム
NTFS ファイル システムでは、 CreateFileTransacted を 使用して、ファイル内に個別のストリームを作成できます。詳細については、「 ファイル ストリーム」を参照してください。
ディレクトリ
アプリケーションでは CreateFileTransacted を使用してディレクトリを作成できないため、このユース ケースでは dwCreationDisposition に対して有効なのはOPEN_EXISTING値のみです。 ディレクトリを作成するには、アプリケーションで CreateDirectoryTransacted、CreateDirectory、または CreateDirectoryEx を呼び出す必要があります。CreateFileTransacted を使用してディレクトリを開くには、dwFlagsAndAttributes の一部として FILE_FLAG_BACKUP_SEMANTICS フラグを指定します。 このフラグが SE_BACKUP_NAME および SE_RESTORE_NAME 特権なしで使用されている場合は、適切なセキュリティ チェックが引き続き適用されます。
FAT または FAT32 ファイル システム ボリュームの最適化中に CreateFileTransacted を使用してディレクトリを開く場合は、 MAXIMUM_ALLOWED アクセス権を指定しないでください。 これが行われた場合、ディレクトリへのアクセスは拒否されます。 代わりに 、GENERIC_READ アクセス権を指定します。
詳細については、「 ディレクトリ管理について」を参照してください。
注意
winbase.h ヘッダーは、CreateFileTransacted をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winbase.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |
関連項目
関数
概要トピック