CreateFileTransactedA 関数 (winbase.h)
[Microsoft では、開発者がアプリケーションのニーズを達成するために代替手段を利用することを強くお勧めします。 TxF が開発された多くのシナリオは、よりシンプルで簡単に利用できる手法によって実現できます。 さらに、将来のバージョンの Microsoft Windows では TxF を使用できない可能性があります。 詳細と TxF の代替方法については、「トランザクション NTFSを使用する
トランザクション操作としてファイル、ファイル ストリーム、またはディレクトリを作成または開きます。 この関数は、オブジェクトへのアクセスに使用できるハンドルを返します。
この操作を非トランザクション操作として実行したり、ファイル以外のオブジェクト (名前付きパイプ、物理デバイス、mailslots など) にアクセスしたりするには、CreateFile 関数を使用します。
トランザクションの詳細については、このトピックの「解説」セクションを参照してください。
構文
HANDLE CreateFileTransactedA(
[in] LPCSTR 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
構造体の bInheritHandle メンバーは、返されたハンドルを継承できるかどうかを指定します。
構造体の
lpSecurityDescriptor メンバー
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
| 属性 | 意味 |
|---|---|
|
ファイルはアーカイブする必要があります。 アプリケーションでは、この属性を使用して、バックアップまたは削除のためにファイルをマークします。 |
|
ファイルまたはディレクトリは暗号化されます。 ファイルの場合、これはファイル内のすべてのデータが暗号化されることを意味します。 ディレクトリの場合は、暗号化が新しく作成されたファイルとサブディレクトリの既定値であることを意味します。 詳細については、「File Encryption」を参照してください。
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 関数を呼び出すことによって、ボリューム セクター サイズを決定できます。 |
|
ファイル データは要求されますが、引き続きリモート ストレージに配置する必要があります。 ローカル ストレージに転送しないでください。 このフラグは、リモート・ストレージ・システムで使用するために使用されます。 |
|
通常 |
|
非同期 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 より前にはサポートされていません。 |
|
ファイルは、最初から最後まで順番にアクセスされます。 システムは、ファイル キャッシュを最適化するためのヒントとしてこれを使用できます。 アプリケーションがランダム アクセスのためにファイル ポインターを移動すると、最適なキャッシュが発生しない可能性があります。 ただし、正しい操作は引き続き保証されます。
このフラグを指定すると、順次アクセスを使用して大きなファイルを読み取るアプリケーションのパフォーマンスが向上する可能性があります。 大きなファイルをほぼ順番に読み取るが、場合によっては小さなバイト範囲をスキップするアプリケーションでは、パフォーマンスの向上がさらに顕著になる可能性があります。 このフラグは、ファイル システムがキャッシュされた I/O と FILE_FLAG_NO_BUFFERINGをサポートしていない場合は影響を与えません。 |
|
書き込み操作は中間キャッシュを経由せず、ディスクに直接移動します。
システム キャッシュが有効になるように FILE_FLAG_NO_BUFFERING も指定されていない場合、データはシステム キャッシュに書き込まれますが、ディスクに遅延なくフラッシュされます。 FILE_FLAG_NO_BUFFERING も指定されているため、システム キャッシュが有効にならない場合、データはシステム キャッシュを経由せずにすぐにディスクにフラッシュされます。 オペレーティング システムは、ハード ディスク キャッシュから永続メディアへの書き込み要求も行います。 ただし、すべてのハードウェアがこのライトスルー機能をサポートしているわけではありません。 |
dwFlagsAndAttributes パラメーターでは、セキュリティサービス品質情報を指定することもできます。 詳細については、「偽装レベルの」を参照してください。 呼び出し元のアプリケーションが dwFlagsAndAttributesの一部として
[in, optional] hTemplateFile
GENERIC_READ アクセス権を持つテンプレート ファイルへの有効なハンドル。 テンプレート ファイルは、作成されるファイルのファイル属性と拡張属性を提供します。 このパラメーターは NULL
既存のファイルを開くと、CreateFileTransacted
新しい EFS で暗号化されたファイルを開くと、そのファイルは親ディレクトリから DACL を継承します。
[in] hTransaction
トランザクションのハンドル。 このハンドルは、CreateTransaction 関数によって返されます。
[in, optional] pusMiniVersion
開くミニバージョン。
lpExtendedParameter
このパラメーターは予約されており、NULL
戻り値
関数が成功した場合、戻り値は、指定されたファイル、デバイス、名前付きパイプ、またはメール スロットへの開いているハンドルです。
関数が失敗した場合、戻り値は INVALID_HANDLE_VALUE。 拡張エラー情報を取得するには、GetLastError
備考
CreateFileTransactedによって返されるハンドル
トランザクション ハンドルをディレクトリに対して開く場合、そのハンドルには FILE_WRITE_DATA (FILE_ADD_FILE) と FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY) のアクセス許可が必要です。 これらは、FILE_GENERIC_WRITE のアクセス許可に含まれています。 ハンドルを使用してファイルまたはサブディレクトリを作成するだけの場合は、アクセス許可の少ないディレクトリを開く必要があります。そうしないと、共有違反が発生する可能性があります。
そのファイルが別のトランザクションの一部である場合(つまり、別のアプリケーションが CreateFileTransactedを呼び出して開いた)、
トランザクションされていないアプリケーションが、lpSecurityAttributesに対して MAXIMUM_ALLOWED を指定 CreateFileTransacted を呼び出すと、毎回同じアクセス レベルでハンドルが開かれます。 トランザクションアプリケーションが
トランザクション操作の詳細については、「トランザクション NTFS」を参照してください。
NTFS ファイル システムなどの一部のファイル システムでは、個々のファイルとディレクトリの圧縮または暗号化がサポートされています。 その種類のファイル システム用にフォーマットされたボリュームでは、新しいファイルは、そのディレクトリの圧縮属性と暗号化属性を継承します。
CreateFileTransacted
シンボリック リンク動作: この関数の呼び出しによって新しいファイルが作成された場合、動作に変更はありません。
FILE_FLAG_OPEN_REPARSE_POINT が指定されている場合:
- 既存のファイルが開き、シンボリック リンクである場合、返されるハンドルはシンボリック リンクへのハンドルです。
- TRUNCATE_EXISTING または FILE_FLAG_DELETE_ON_CLOSE が指定されている場合、影響を受けるファイルはシンボリック リンクです。
- 既存のファイルが開き、それがシンボリック リンクである場合、返されるハンドルはターゲットへのハンドルです。
- CREATE_ALWAYS、TRUNCATE_EXISTING、または FILE_FLAG_DELETE_ON_CLOSE が指定されている場合、影響を受けるファイルがターゲットです。
前述のように、
bInheritHandle が FALSE(0 以外の値)されていない場合は、ハンドルを継承できます。 したがって、ハンドルを継承できない場合は、FALSE を するためにこの構造体メンバーを適切に初期化することが重要です。 - ファイルまたはディレクトリの既定のセキュリティ記述子のアクセス制御リスト (ACL) は、親ディレクトリから継承されます。
- ターゲット ファイル システムは、lpSecurityDescriptor がそれらに影響を与えるために、ファイルとディレクトリのセキュリティをサポートする必要があります。これは、GetVolumeInformation を使用して決定できます
| テクノロジー | サポート |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | いいえ |
| SMB 3.0 透過的フェールオーバー (TFO) | いいえ |
| SMB 3.0 とスケールアウト ファイル共有 (SO) | いいえ |
| クラスター共有ボリューム ファイル システム (CsvFS) | いいえ |
| 回復性のあるファイル システム (ReFS) | いいえ |
SMB 3.0 では TxF がサポートされないことに注意してください。
ファイル
フロッピー ディスクを持たないフロッピー ドライブまたは CD を持たない CD-ROM ドライブにファイルを作成しようとすると、ディスクまたは CD を挿入するためのメッセージが表示されます。 システムがこのメッセージを表示しないようにするには、SEM_FAILCRITICALERRORSを使用して SetErrorMode 関数を呼び出します。詳細については、「ファイルの作成と開く」を参照してください。
ファイルの名前を変更または削除し、その後すぐに復元すると、システムはキャッシュで復元するファイル情報を検索します。 キャッシュされた情報には、短い名前と長い名前のペアと作成時間が含まれます。
DeleteFile
dwDesiredAccess パラメーターは 0 にすることができ、アプリケーションが適切なセキュリティ設定で実行されている場合、アプリケーションはファイルにアクセスせずにファイル属性を照会できます。 これは、読み取り/書き込みアクセスのためにファイルを開かずにファイルの存在をテストしたり、ファイルまたはディレクトリに関するその他の統計情報を取得したりする場合に便利です。 GetFileInformationByHandle および
アプリケーションがネットワーク経由でファイルを作成する場合は、GENERIC_WRITE を単独で使用するよりも | GENERIC_WRITE を使用することをお勧めします。 リダイレクターはキャッシュ マネージャーを使用でき、送信するデータの数が少ない SMB を減らすことができるため、結果のコードは高速になります。 この組み合わせにより、ネットワーク経由でファイルに書き込むときに ERROR_ACCESS_DENIEDが返される場合がある問題も回避できます。
ファイル ストリーム
NTFS ファイル システムでは、CreateFileTransacted を使用して、ファイル内に個別のストリームを作成できます。詳細については、「ファイル ストリームの」を参照してください。
ディレクトリ
アプリケーションは CreateFileTransactedCreateFileTransacted
CreateFileTransacted を使用して FAT または FAT32 ファイル システム ボリュームの最適化中にディレクトリを開く場合は、MAXIMUM_ALLOWED アクセス権を指定しないでください。 この操作を行うと、ディレクトリへのアクセスが拒否されます。 代わりに、GENERIC_READ アクセス権を指定します。
詳細については、「ディレクトリ管理について」を参照してください。
手記
winbase.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして CreateFileTransacted を定義します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされる最小サーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | winbase.h (Windows.h を含む) |
| ライブラリ | Kernel32.lib |
| DLL | Kernel32.dll |
関連項目
CloseHandle の
CreateDirectoryTransacted の
DeleteFileTransacted の
FindFirstFileTransacted の
Functions
GetFileAttributesTransacted の
MoveFileTransacted の
の概要に関するトピック
トランザクション NTFS の
ReadFile の
トランザクション NTFS (TxF) の
WriteFile の