Win32 API 日本語リファレンス
ホームStorage.FileSystem › CreateFileTransactedW

CreateFileTransactedW

関数
トランザクション内でファイルを作成・オープンする(Unicode版)。
DLLKERNEL32.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

HANDLE CreateFileTransactedW(
    LPCWSTR lpFileName,
    DWORD dwDesiredAccess,
    FILE_SHARE_MODE dwShareMode,
    SECURITY_ATTRIBUTES* lpSecurityAttributes,   // optional
    FILE_CREATION_DISPOSITION dwCreationDisposition,
    FILE_FLAGS_AND_ATTRIBUTES dwFlagsAndAttributes,
    HANDLE hTemplateFile,   // optional
    HANDLE hTransaction,
    TXFS_MINIVERSION* pusMiniVersion,   // optional
    void* lpExtendedParameter   // optional
);

パラメーター

名前方向説明
lpFileNameLPCWSTRin

作成または開くオブジェクトの名前。

オブジェクトはローカルコンピューター上に存在している必要があります。そうでない場合、 関数は失敗し、最終エラーコードに ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE が設定されます。

既定では、名前は MAX_PATH 文字に制限されます。この制限を 32,767 ワイド文字まで拡張するには、パスの先頭に "\\?\" を付加します。詳細については、ファイル、パス、名前空間の名前付け を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を付加せずに MAX_PATH 制限を解除するオプトインが可能です。詳細については、ファイル、パス、名前空間の名前付け の「Maximum Path Length Limitation」セクションを参照してください。

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

dwDesiredAccessDWORDin

オブジェクトへのアクセス。読み取り、書き込み、その両方、またはどちらでもない(ゼロ)に要約できます。最もよく 使用される値は GENERIC_READGENERIC_WRITE、またはその両方 (GENERIC_READ | GENERIC_WRITE) です。詳細については、 Generic Access Rights および File Security and Access Rights を参照してください。

このパラメーターがゼロの場合、アプリケーションはファイル、ディレクトリ、またはデバイスにアクセスせずに、それらの属性を照会できます。 詳細については、本トピックの「解説」セクションを参照してください。

オープンハンドルを持つオープン要求で指定された共有モードと競合するアクセスモードを要求することはできません。詳細については、 Creating and Opening Files を参照してください。

dwShareModeFILE_SHARE_MODEin

オブジェクトの共有モード。読み取り、書き込み、その両方、削除、これらすべて、またはいずれでもない(次の 表を参照)を指定できます。

このパラメーターがゼロで CreateFileTransacted が成功した場合、オブジェクトは 共有できず、ハンドルが閉じられるまで再度開くことはできません。詳細については、本トピックの「解説」セクション を参照してください。

オープンハンドルを持つオープン要求で指定されたアクセスモードと競合する共有モードを要求することはできません。要求した場合、 次の共有違反が発生します。 ERROR_SHARING_VIOLATION。詳細については、 Creating and Opening Files を参照してください。

別のプロセスがオブジェクトを開いている間にプロセスがそのオブジェクトを共有できるようにするには、次の値の 1 つ以上を組み合わせて、オブジェクトを開く際に要求できるアクセスモードを指定します。

注意 各オープンハンドルの共有オプションは、プロセスのコンテキストに関係なく、そのハンドルが閉じられるまで 有効です。
意味
0
0x00000000
オブジェクトに対するその後のオープン操作で、そのオブジェクトへのいかなる種類のアクセスも要求できないようにします。
FILE_SHARE_DELETE
0x00000004
オブジェクトに対するその後のオープン操作で、削除アクセスを要求できるようにします。

そうでない場合、他のプロセスは削除アクセスを要求するとオブジェクトを開けません。

このフラグが指定されておらず、オブジェクトが既に削除アクセスで開かれている場合、関数は失敗します。

FILE_SHARE_READ
0x00000001
オブジェクトに対するその後のオープン操作で、読み取りアクセスを要求できるようにします。

そうでない場合、他のプロセスは読み取りアクセスを要求するとオブジェクトを開けません。

このフラグが指定されておらず、オブジェクトが既に読み取りアクセスで開かれている場合、関数は失敗します。

FILE_SHARE_WRITE
0x00000002
オブジェクトに対するその後のオープン操作で、書き込みアクセスを要求できるようにします。

そうでない場合、他のプロセスは書き込みアクセスを要求するとオブジェクトを開けません。

このフラグが指定されておらず、オブジェクトが既に書き込みアクセスで開かれているか、書き込みアクセスを持つファイルマッピングを 持っている場合、関数は失敗します。

lpSecurityAttributesSECURITY_ATTRIBUTES*inoptional

SECURITY_ATTRIBUTES 構造体へのポインター。この構造体には、省略可能な セキュリティ記述子 が含まれ、返されるハンドルを 子プロセスが継承できるかどうかも決定します。このパラメーターには NULL を指定できます。

lpSecurityAttributes パラメーターが NULL の場合、 CreateFileTransacted によって返されるハンドルは、 アプリケーションが作成する子プロセスによって継承できず、返されたハンドルに関連付けられたオブジェクトには 既定のセキュリティ記述子が割り当てられます。

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

構造体の lpSecurityDescriptor メンバーは、オブジェクトの セキュリティ記述子 を指定しますが、 NULL にすることもできます。

lpSecurityDescriptor メンバーが NULL の場合、返されたハンドルに 関連付けられたオブジェクトには既定のセキュリティ記述子が割り当てられます。

CreateFileTransacted は、既存のファイルを開く際には lpSecurityDescriptor メンバーを無視しますが、引き続き bInheritHandle メンバーを使用します。

詳細については、本トピックの「解説」セクションを参照してください。

dwCreationDispositionFILE_CREATION_DISPOSITIONin

存在するファイルおよび存在しないファイルに対して行うアクション。

詳細については、本トピックの「解説」セクションを参照してください。

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

意味
CREATE_ALWAYS
2
常に新しいファイルを作成します。

指定されたファイルが存在し、書き込み可能な場合、関数はファイルを切り詰め、関数は成功し、 最終エラーコードに ERROR_ALREADY_EXISTS (183) が設定されます。

指定されたファイルが存在せず、有効なパスである場合、新しいファイルが作成され、関数は成功し、 最終エラーコードにゼロが設定されます。

詳細については、本トピックの「解説」セクションを参照してください。

CREATE_NEW
1
ファイルが存在しない場合にのみ、新しいファイルを作成します。

指定されたファイルが存在する場合、関数は失敗し、最終エラーコードに ERROR_FILE_EXISTS (80) が設定されます。

指定されたファイルが存在せず、書き込み可能な場所への有効なパスである場合、新しいファイルが作成されます。

OPEN_ALWAYS
4
常にファイルを開きます。

指定されたファイルが存在する場合、関数は成功し、最終エラーコードに ERROR_ALREADY_EXISTS (183) が設定されます。

指定されたファイルが存在せず、書き込み可能な場所への有効なパスである場合、関数はファイルを 作成し、最終エラーコードにゼロが設定されます。

OPEN_EXISTING
3
ファイルまたはデバイスが存在する場合にのみ開きます。

指定されたファイルが存在しない場合、関数は失敗し、最終エラーコードに ERROR_FILE_NOT_FOUND (2) が設定されます。

詳細については、本トピックの「解説」セクションを参照してください。

TRUNCATE_EXISTING
5
ファイルが存在する場合にのみ、ファイルを開いてサイズが 0 バイトになるように切り詰めます。

指定されたファイルが存在しない場合、関数は失敗し、最終エラーコードに ERROR_FILE_NOT_FOUND (2) が設定されます。

呼び出し元のプロセスは、dwDesiredAccess パラメーターの一部として GENERIC_WRITE ビットを設定してファイルを開く必要があります。

dwFlagsAndAttributesFILE_FLAGS_AND_ATTRIBUTESin

ファイル属性とフラグ。FILE_ATTRIBUTE_NORMAL が最も一般的な既定 値です。

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

このパラメーターには、バッファリング動作、アクセスモード、その他の特殊用途のフラグを制御するための フラグ (FILE_FLAG_*) の組み合わせを含めることもできます。これらは任意の FILE_ATTRIBUTE_* 値と組み合わせられます。

このパラメーターには、SECURITY_SQOS_PRESENT フラグを指定することで、 Security Quality of Service (SQOS) 情報を含めることもできます。SQOS 関連の追加フラグ情報は、 属性とフラグの表の後の表に示されています。

注意

CreateFileTransacted が既存の ファイルを開くとき、一般にファイルフラグを既存ファイルのファイル属性と組み合わせ、 dwFlagsAndAttributes の一部として指定されたファイル属性は無視します。特殊なケースの詳細は Creating and Opening Files に記載されています。

次のファイル属性とフラグは、ファイルオブジェクトに対してのみ使用され、 CreateFileTransacted が開く他の種類のオブジェクトには使用されません(追加 情報は本トピックの「解説」セクションにあります)。ファイル属性へのより高度なアクセスについては、 SetFileAttributes を参照してください。すべての ファイル属性とその値および説明の完全な一覧については、 File Attribute Constants を参照してください。
属性 意味
FILE_ATTRIBUTE_ARCHIVE
32 (0x20)
ファイルをアーカイブする必要があります。アプリケーションはこの属性を使用して、バックアップまたは削除の対象となるファイルをマークします。
FILE_ATTRIBUTE_ENCRYPTED
16384 (0x4000)
ファイルまたはディレクトリが暗号化されています。ファイルの場合、これはファイル内のすべてのデータが暗号化されていることを意味します。 ディレクトリの場合、これは新しく作成されるファイルとサブディレクトリで暗号化が既定であることを意味します。詳細については、 File Encryption を参照してください。

FILE_ATTRIBUTE_SYSTEM も指定されている場合、このフラグは効果がありません。

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 特権を持つ場合、システムは呼び出し元プロセスがファイルセキュリティチェックを オーバーライドすることを保証します。詳細については、 Changing Privileges in a Token を参照してください。

ディレクトリへのハンドルを取得するには、このフラグを設定する必要があります。ディレクトリハンドルは、一部の 関数にファイルハンドルの代わりに渡すことができます。詳細については、 Directory Handles を参照してください。

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
トランザクションがまだアクティブであることを条件として、ファイルへの最後のトランザクション書き込みハンドルが閉じられた直後に ファイルが削除されます。ファイルが削除対象としてマークされ、トランザクションの完了後もトランザクション書き込みハンドルが 開いたままである場合、ファイルは削除されません。

ファイルへの既存のオープンハンドルが存在する場合、それらがすべて FILE_SHARE_DELETE 共有モードで開かれていない限り、呼び出しは失敗します。

FILE_SHARE_DELETE 共有モードが指定されていない限り、ファイルに対するその後のオープン 要求は失敗します。

FILE_FLAG_NO_BUFFERING
0x20000000
ファイルはシステムキャッシュなしで開かれます。このフラグはハードディスクのキャッシュやメモリ マップファイルには影響しません。FILE_FLAG_OVERLAPPED と組み合わせると、I/O が メモリマネージャーの同期操作に依存しないため、最大の非同期パフォーマンスが得られます。 ただし、データがキャッシュに保持されないため、一部の I/O 操作はより多くの時間がかかります。また、ファイル メタデータは依然としてキャッシュされる場合があります。メタデータをディスクにフラッシュするには、 FlushFileBuffers 関数を使用します。

アプリケーションは、FILE_FLAG_NO_BUFFERING で開かれたファイルを操作する際に、 一定の要件を満たす必要があります。

  • ファイルアクセスは、ボリュームのセクターサイズの整数倍であるファイル内のバイトオフセットから開始する必要が あります。
  • ファイルアクセスは、ボリュームのセクターサイズの整数倍であるバイト数で行う必要があります。たとえば、 セクターサイズが 512 バイトの場合、アプリケーションは 512、1024、1536、 または 2048 バイトの読み取りと書き込みを要求できますが、335、981、または 7171 バイトは要求できません。
  • 読み取りおよび書き込み操作のバッファーアドレスはセクター境界に合わせる必要があります。これは、メモリ内の ボリュームのセクターサイズの整数倍であるアドレスに合わせることを意味します。ディスクによっては、この 要件が強制されない場合があります。
ボリュームのセクターサイズの整数倍にバッファーを合わせる 1 つの方法は、 VirtualAlloc を使用してバッファーを割り当てることです。これは、 オペレーティングシステムのメモリページサイズの整数倍であるアドレスに合わせてメモリを割り当てます。 メモリページとボリュームのセクターサイズはどちらも 2 のべき乗であるため、このメモリは ボリュームのセクターサイズの整数倍であるアドレスにも合わせられます。メモリページのサイズは 4 または 8 KB で、セクターは 512 バイト (ハードディスク)、2048 バイト (CD)、または 4096 バイト (ハードディスク) であるため、ボリュームセクターが メモリページより大きくなることはありません。

アプリケーションは、 GetDiskFreeSpace 関数を呼び出すことで、ボリュームのセクターサイズを判別できます。

FILE_FLAG_OPEN_NO_RECALL
0x00100000
ファイルデータが要求されますが、引き続きリモートストレージに配置されたままにする必要があります。 ローカルストレージに戻して転送すべきではありません。このフラグはリモートストレージシステムで使用します。
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
通常の 再解析ポイント 処理は行われません。 CreateFileTransacted は再解析ポイントを開こうとします。ファイルが開かれると、 再解析ポイントを制御するフィルターが動作しているかどうかにかかわらず、ファイルハンドルが返されます。 このフラグは CREATE_ALWAYS フラグと併用できません。ファイルが再解析ポイントでない場合、 このフラグは無視されます。
FILE_FLAG_OVERLAPPED
0x40000000
ファイルは非同期 I/O のために開かれるか作成されています。操作が完了すると、 OVERLAPPED 構造体で指定されたイベントが シグナル状態に設定されます。処理にかなりの時間を要する操作は、 ERROR_IO_PENDING を返します。

このフラグが指定されている場合、ファイルは読み取りと書き込みの同時操作に使用できます。システムは ファイルポインターを保持しないため、読み取り関数と書き込み関数にファイル位置を OVERLAPPED 構造体で渡すか、ファイル ポインターを更新する必要があります。

このフラグが指定されていない場合、読み取り関数と書き込み関数の呼び出しが OVERLAPPED 構造体を指定していても、I/O 操作は直列化されます。

FILE_FLAG_POSIX_SEMANTICS
0x01000000
ファイルは POSIX 規則に従ってアクセスされます。これには、その命名をサポートするファイルシステムで、 大文字と小文字のみが異なる複数のファイルを許可することが含まれます。このフラグで作成された ファイルは MS-DOS または 16 ビット Windows 向けに書かれたアプリケーションからアクセスできない場合があるため、 このオプションを使用する際は注意してください。
FILE_FLAG_RANDOM_ACCESS
0x10000000
ファイルはランダムにアクセスされます。システムはこれをファイルキャッシュを最適化するためのヒントとして使用できます。
FILE_FLAG_SESSION_AWARE
0x00800000
ファイルまたはデバイスはセッション認識付きで開かれます。このフラグが指定されていない場合、セッション 0 で実行されている プロセスは、セッションごとのデバイス(RemoteFX USB リダイレクションを使用するデバイスなど)を開くことができません。 このフラグは、セッション 0 にない呼び出し元には効果がありません。このフラグは Windows のサーバーエディションでのみサポートされます。

Windows Server 2008 R2 および Windows Server 2008: このフラグは Windows Server 2012 より前ではサポートされません。

FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
ファイルは先頭から末尾まで順次アクセスされます。システムはこれをファイルキャッシュを 最適化するためのヒントとして使用できます。アプリケーションがランダムアクセスのためにファイルポインターを移動する場合、最適なキャッシュが 行われない場合があります。ただし、正しい動作は引き続き保証されます。

このフラグを指定すると、順次アクセスを使用して大きなファイルを読み取るアプリケーションのパフォーマンスを 向上させることができます。大きなファイルを主に順次に読み取るものの、 小さなバイト範囲を時々スキップするアプリケーションでは、パフォーマンスの向上がさらに顕著になることがあります。

ファイルシステムがキャッシュ I/O と FILE_FLAG_NO_BUFFERING をサポートしていない場合、このフラグは効果がありません。

FILE_FLAG_WRITE_THROUGH
0x80000000
書き込み操作は中間キャッシュを経由せず、直接ディスクに書き込まれます。

FILE_FLAG_NO_BUFFERING も指定されておらず、システムキャッシュが 有効な場合、データはシステムキャッシュに書き込まれますが、遅延なくディスクにフラッシュされます。

FILE_FLAG_NO_BUFFERING も指定されており、システムキャッシュが無効 な場合、データはシステムキャッシュを経由せずに直ちにディスクにフラッシュされます。オペレーティング システムは、ハードディスクキャッシュから永続メディアへのライトスルーも要求します。ただし、すべてのハードウェアが このライトスルー機能をサポートしているわけではありません。

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

セキュリティフラグ 意味
SECURITY_ANONYMOUS
匿名 (Anonymous) 偽装レベルでクライアントを偽装します。
SECURITY_CONTEXT_TRACKING
セキュリティ追跡モードは動的です。このフラグが指定されていない場合、セキュリティ追跡モードは 静的です。
SECURITY_DELEGATION
委任 (Delegation) 偽装レベルでクライアントを偽装します。
SECURITY_EFFECTIVE_ONLY
クライアントのセキュリティコンテキストの有効化された側面のみがサーバーで利用可能になります。このフラグを 指定しない場合、クライアントのセキュリティコンテキストのすべての側面が利用可能になります。

これにより、クライアントは、サーバーがクライアントを偽装する間に使用できるグループと特権を制限できます。

SECURITY_IDENTIFICATION
識別 (Identification) 偽装レベルでクライアントを偽装します。
SECURITY_IMPERSONATION
偽装 (Impersonation) レベルでクライアントを偽装します。これは、SECURITY_SQOS_PRESENT フラグと共に 他のフラグが指定されていない場合の既定の動作です。
hTemplateFileHANDLEinoptional

GENERIC_READ アクセス権を持つテンプレートファイルへの有効なハンドル。テンプレート ファイルは、作成中のファイルのファイル属性と拡張属性を提供します。このパラメーターには NULL を指定できます。

既存のファイルを開く際、 CreateFileTransacted はテンプレート ファイルを無視します。

新しい EFS 暗号化ファイルを開く際、ファイルは親ディレクトリから DACL を継承します。

hTransactionHANDLEinトランザクションへのハンドル。このハンドルは CreateTransaction 関数によって返されます。
pusMiniVersionTXFS_MINIVERSION*inoptional

開くミニバージョン。hTransaction で指定されたトランザクションが ファイルを変更しているトランザクションでない場合、このパラメーターは NULL である必要があります。そうでない場合、 このパラメーターには、FSCTL_TXFS_CREATE_MINIVERSION 制御 コードによって返されるミニバージョン識別子、または次のいずれかの値を指定できます。

意味
TXFS_MINIVERSION_COMMITTED_VIEW
0x0000
最後のコミット時点でのファイルのビュー。
TXFS_MINIVERSION_DIRTY_VIEW
0xFFFF
トランザクションによって変更されている状態のファイルのビュー。
TXFS_MINIVERSION_DEFAULT_VIEW
0xFFFE
コンテキストに応じて、ファイルのコミット済みビューまたはダーティビューのいずれか。ファイルを変更している トランザクションはダーティビューを取得し、ファイルを変更していないトランザクションはコミット済み ビューを取得します。
lpExtendedParametervoid*optionalこのパラメーターは予約されており、NULL である必要があります。

戻り値の型: HANDLE

公式ドキュメント

ファイル、ファイルストリーム、またはディレクトリをトランザクション操作として作成または開きます。(Unicode)

戻り値

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

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

解説(Remarks)

CreateFileTransacted が返すハンドルを使用する際は、 適切な場合には標準のファイル I/O 関数の代わりに、トランザクション版の ファイル I/O 関数を使用してください。詳細については、 Programming Considerations for Transactional 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 が失敗することを意味します。

トランザクション化されていないアプリケーションが lpSecurityAttributesMAXIMUM_ALLOWED を指定して CreateFileTransacted を呼び出す場合、ハンドルは 毎回同じアクセスレベルで開かれます。トランザクション化されたアプリケーションが lpSecurityAttributesMAXIMUM_ALLOWED を指定して CreateFileTransacted を呼び出す場合、ハンドルは ファイルがトランザクションによってロックされているかどうかに基づいて、異なる量のアクセスで開かれます。たとえば、 呼び出し元アプリケーションがファイルに対して FILE_EXECUTE アクセスレベルを持っている場合、アプリケーションは 開こうとしているファイルがトランザクションによってロックされていないか、トランザクションによってロックされていて アプリケーションが既にそのファイルのトランザクション読み取り元である場合にのみ、このアクセスを取得します。

トランザクション操作の完全な説明については、Transactional NTFS を 参照してください。

CreateFileTransacted によって返されたオブジェクトハンドルが不要になったとき、かつトランザクションの コミットまたはロールバックの前に、そのハンドルを閉じるには CloseHandle 関数を使用します。

NTFS ファイルシステムなどの一部のファイルシステムは、個々のファイルや ディレクトリの圧縮または暗号化をサポートします。そのようなファイルシステム用にフォーマットされたボリュームでは、新しいファイルは そのディレクトリの圧縮属性と暗号化属性を継承します。

CreateFileTransacted を使用してファイルやディレクトリの 圧縮を制御することはできません。詳細については、 File Compression and Decompression および File Encryption を参照してください。

シンボリックリンクの動作—この関数の呼び出しが新しいファイルを作成する場合、動作に 変化はありません。

FILE_FLAG_OPEN_REPARSE_POINT が指定されている場合:

FILE_FLAG_OPEN_REPARSE_POINT が指定されていない場合: トランザクションを使用している場合(つまり、作成されたハンドルがトランザクションハンドルである場合)を除き、複数セクターの書き込みが アトミックであることは保証されません。単一セクターの書き込みはアトミックです。キャッシュされる複数セクターの書き込みは 必ずしもディスクに書き込まれるとは限りません。そのため、複数セクターの書き込み全体がキャッシュなしで ディスクに書き込まれることを保証するには、FILE_FLAG_WRITE_THROUGH を指定してください。

前述のとおり、lpSecurityAttributes パラメーターが NULL の場合、CreateFileTransacted によって返されるハンドルは、アプリケーションが 作成する子プロセスによって継承できません。このパラメーターに関する次の情報も適用されます。

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジによってサポートされます。
テクノロジ サポート
Server Message Block (SMB) 3.0 プロトコル いいえ
SMB 3.0 Transparent Failover (TFO) いいえ
SMB 3.0 with Scale-out File Shares (SO) いいえ
Cluster Shared Volume File System (CsvFS) いいえ
Resilient File System (ReFS) いいえ

SMB 3.0 は TxF をサポートしないことに注意してください。

ファイル

フロッピーディスクが入っていないフロッピードライブ、または CD が入っていない CD-ROM ドライブ上に ファイルを作成しようとすると、システムはディスクまたは CD を挿入するようユーザーにメッセージを表示します。システムが このメッセージを表示しないようにするには、SetErrorMode 関数を SEM_FAILCRITICALERRORS で呼び出します。

詳細については、 Creating and Opening Files を参照してください。

ファイルの名前を変更または削除した後、すぐに復元すると、システムは復元するファイル情報を キャッシュから検索します。キャッシュされた情報には、短い名前と長い名前のペアおよび作成時刻が含まれます。

以前の DeleteFile の呼び出しの結果として 削除が保留されているファイルに対して CreateFileTransacted を呼び出すと、関数は失敗します。オペレーティングシステムは ファイルへのすべてのハンドルが閉じられるまでファイルの削除を遅延します。 GetLastErrorERROR_ACCESS_DENIED を返します。

dwDesiredAccess パラメーターは ゼロにすることができ、アプリケーションが適切なセキュリティ設定で実行されている場合、ファイルにアクセスせずに ファイル属性を照会できます。これは、ファイルを読み取りまたは書き込みアクセスで開かずにファイルの存在を テストしたり、ファイルやディレクトリに関するその他の統計情報を取得したりするのに役立ちます。 Obtaining and Setting File Information および GetFileInformationByHandle を参照してください。

アプリケーションがネットワーク経由でファイルを作成する場合、GENERIC_WRITE 単独を使用するよりも GENERIC_READ | GENERIC_WRITE を使用する方が適切です。リダイレクターが キャッシュマネージャーを使用し、より多くのデータを含むより少ない SMB を送信できるため、結果のコードは 高速になります。この組み合わせは、ネットワーク経由でファイルに書き込む際に時々 ERROR_ACCESS_DENIED が 返される問題も回避します。

ファイルストリーム

NTFS ファイルシステムでは、 CreateFileTransacted を使用してファイル内に個別のストリームを 作成できます。

詳細については、 File Streams を参照してください。

ディレクトリ

アプリケーションは CreateFileTransacted を使用してディレクトリを作成できないため、この用途では dwCreationDisposition に有効な値は OPEN_EXISTING のみです。ディレクトリを作成するには、 アプリケーションは CreateDirectoryTransactedCreateDirectory、または CreateDirectoryEx を呼び出す必要があります。

CreateFileTransacted を使用してディレクトリを開くには、 dwFlagsAndAttributes の一部として FILE_FLAG_BACKUP_SEMANTICS フラグを指定します。 このフラグを SE_BACKUP_NAME および SE_RESTORE_NAME 特権なしで使用する場合、適切なセキュリティチェックが引き続き適用されます。

FAT または FAT32 ファイルシステムボリュームのデフラグ中に CreateFileTransacted を使用して ディレクトリを開く場合は、MAXIMUM_ALLOWED アクセス権を指定しないでください。これを行うと ディレクトリへのアクセスが拒否されます。代わりに GENERIC_READ アクセス権を指定してください。

詳細については、 About Directory Management を参照してください。

メモ

winbase.h ヘッダーは CreateFileTransacted を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義します。エンコーディング中立のエイリアスの使用を、エンコーディング中立でないコードと混在させると、コンパイルエラーまたは実行時エラーを引き起こす不一致が生じる可能性があります。詳細については、Conventions for Function Prototypes を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

HANDLE CreateFileTransactedW(
    LPCWSTR lpFileName,
    DWORD dwDesiredAccess,
    FILE_SHARE_MODE dwShareMode,
    SECURITY_ATTRIBUTES* lpSecurityAttributes,   // optional
    FILE_CREATION_DISPOSITION dwCreationDisposition,
    FILE_FLAGS_AND_ATTRIBUTES dwFlagsAndAttributes,
    HANDLE hTemplateFile,   // optional
    HANDLE hTransaction,
    TXFS_MINIVERSION* pusMiniVersion,   // optional
    void* lpExtendedParameter   // optional
);
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern IntPtr CreateFileTransactedW(
    [MarshalAs(UnmanagedType.LPWStr)] string lpFileName,   // LPCWSTR
    uint dwDesiredAccess,   // DWORD
    uint dwShareMode,   // FILE_SHARE_MODE
    IntPtr lpSecurityAttributes,   // SECURITY_ATTRIBUTES* optional
    uint dwCreationDisposition,   // FILE_CREATION_DISPOSITION
    uint dwFlagsAndAttributes,   // FILE_FLAGS_AND_ATTRIBUTES
    IntPtr hTemplateFile,   // HANDLE optional
    IntPtr hTransaction,   // HANDLE
    IntPtr pusMiniVersion,   // TXFS_MINIVERSION* optional
    IntPtr lpExtendedParameter   // void* optional
);
<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CreateFileTransactedW(
    <MarshalAs(UnmanagedType.LPWStr)> lpFileName As String,   ' LPCWSTR
    dwDesiredAccess As UInteger,   ' DWORD
    dwShareMode As UInteger,   ' FILE_SHARE_MODE
    lpSecurityAttributes As IntPtr,   ' SECURITY_ATTRIBUTES* optional
    dwCreationDisposition As UInteger,   ' FILE_CREATION_DISPOSITION
    dwFlagsAndAttributes As UInteger,   ' FILE_FLAGS_AND_ATTRIBUTES
    hTemplateFile As IntPtr,   ' HANDLE optional
    hTransaction As IntPtr,   ' HANDLE
    pusMiniVersion As IntPtr,   ' TXFS_MINIVERSION* optional
    lpExtendedParameter As IntPtr   ' void* optional
) As IntPtr
End Function
' lpFileName : LPCWSTR
' dwDesiredAccess : DWORD
' dwShareMode : FILE_SHARE_MODE
' lpSecurityAttributes : SECURITY_ATTRIBUTES* optional
' dwCreationDisposition : FILE_CREATION_DISPOSITION
' dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES
' hTemplateFile : HANDLE optional
' hTransaction : HANDLE
' pusMiniVersion : TXFS_MINIVERSION* optional
' lpExtendedParameter : void* optional
Declare PtrSafe Function CreateFileTransactedW Lib "kernel32" ( _
    ByVal lpFileName As LongPtr, _
    ByVal dwDesiredAccess As Long, _
    ByVal dwShareMode As Long, _
    ByVal lpSecurityAttributes As LongPtr, _
    ByVal dwCreationDisposition As Long, _
    ByVal dwFlagsAndAttributes As Long, _
    ByVal hTemplateFile As LongPtr, _
    ByVal hTransaction As LongPtr, _
    ByVal pusMiniVersion As LongPtr, _
    ByVal lpExtendedParameter As LongPtr) As LongPtr
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

CreateFileTransactedW = ctypes.windll.kernel32.CreateFileTransactedW
CreateFileTransactedW.restype = ctypes.c_void_p
CreateFileTransactedW.argtypes = [
    wintypes.LPCWSTR,  # lpFileName : LPCWSTR
    wintypes.DWORD,  # dwDesiredAccess : DWORD
    wintypes.DWORD,  # dwShareMode : FILE_SHARE_MODE
    ctypes.c_void_p,  # lpSecurityAttributes : SECURITY_ATTRIBUTES* optional
    wintypes.DWORD,  # dwCreationDisposition : FILE_CREATION_DISPOSITION
    wintypes.DWORD,  # dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES
    wintypes.HANDLE,  # hTemplateFile : HANDLE optional
    wintypes.HANDLE,  # hTransaction : HANDLE
    ctypes.c_void_p,  # pusMiniVersion : TXFS_MINIVERSION* optional
    ctypes.POINTER(None),  # lpExtendedParameter : void* optional
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
CreateFileTransactedW = Fiddle::Function.new(
  lib['CreateFileTransactedW'],
  [
    Fiddle::TYPE_VOIDP,  # lpFileName : LPCWSTR
    -Fiddle::TYPE_INT,  # dwDesiredAccess : DWORD
    -Fiddle::TYPE_INT,  # dwShareMode : FILE_SHARE_MODE
    Fiddle::TYPE_VOIDP,  # lpSecurityAttributes : SECURITY_ATTRIBUTES* optional
    -Fiddle::TYPE_INT,  # dwCreationDisposition : FILE_CREATION_DISPOSITION
    -Fiddle::TYPE_INT,  # dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES
    Fiddle::TYPE_VOIDP,  # hTemplateFile : HANDLE optional
    Fiddle::TYPE_VOIDP,  # hTransaction : HANDLE
    Fiddle::TYPE_VOIDP,  # pusMiniVersion : TXFS_MINIVERSION* optional
    Fiddle::TYPE_VOIDP,  # lpExtendedParameter : void* optional
  ],
  Fiddle::TYPE_VOIDP)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"
#[link(name = "kernel32")]
extern "system" {
    fn CreateFileTransactedW(
        lpFileName: *const u16,  // LPCWSTR
        dwDesiredAccess: u32,  // DWORD
        dwShareMode: u32,  // FILE_SHARE_MODE
        lpSecurityAttributes: *mut SECURITY_ATTRIBUTES,  // SECURITY_ATTRIBUTES* optional
        dwCreationDisposition: u32,  // FILE_CREATION_DISPOSITION
        dwFlagsAndAttributes: u32,  // FILE_FLAGS_AND_ATTRIBUTES
        hTemplateFile: *mut core::ffi::c_void,  // HANDLE optional
        hTransaction: *mut core::ffi::c_void,  // HANDLE
        pusMiniVersion: *mut u32,  // TXFS_MINIVERSION* optional
        lpExtendedParameter: *mut ()  // void* optional
    ) -> *mut core::ffi::c_void;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern IntPtr CreateFileTransactedW([MarshalAs(UnmanagedType.LPWStr)] string lpFileName, uint dwDesiredAccess, uint dwShareMode, IntPtr lpSecurityAttributes, uint dwCreationDisposition, uint dwFlagsAndAttributes, IntPtr hTemplateFile, IntPtr hTransaction, IntPtr pusMiniVersion, IntPtr lpExtendedParameter);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_CreateFileTransactedW' -Namespace Win32 -PassThru
# $api::CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter)
#uselib "KERNEL32.dll"
#func global CreateFileTransactedW "CreateFileTransactedW" wptr, wptr, wptr, wptr, wptr, wptr, wptr, wptr, wptr, wptr
; CreateFileTransactedW lpFileName, dwDesiredAccess, dwShareMode, varptr(lpSecurityAttributes), dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, varptr(pusMiniVersion), lpExtendedParameter   ; 戻り値は stat
; lpFileName : LPCWSTR -> "wptr"
; dwDesiredAccess : DWORD -> "wptr"
; dwShareMode : FILE_SHARE_MODE -> "wptr"
; lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> "wptr"
; dwCreationDisposition : FILE_CREATION_DISPOSITION -> "wptr"
; dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> "wptr"
; hTemplateFile : HANDLE optional -> "wptr"
; hTransaction : HANDLE -> "wptr"
; pusMiniVersion : TXFS_MINIVERSION* optional -> "wptr"
; lpExtendedParameter : void* optional -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "KERNEL32.dll"
#cfunc global CreateFileTransactedW "CreateFileTransactedW" wstr, int, int, var, int, int, sptr, sptr, var, sptr
; res = CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter)
; lpFileName : LPCWSTR -> "wstr"
; dwDesiredAccess : DWORD -> "int"
; dwShareMode : FILE_SHARE_MODE -> "int"
; lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> "var"
; dwCreationDisposition : FILE_CREATION_DISPOSITION -> "int"
; dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> "int"
; hTemplateFile : HANDLE optional -> "sptr"
; hTransaction : HANDLE -> "sptr"
; pusMiniVersion : TXFS_MINIVERSION* optional -> "var"
; lpExtendedParameter : void* optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; HANDLE CreateFileTransactedW(LPCWSTR lpFileName, DWORD dwDesiredAccess, FILE_SHARE_MODE dwShareMode, SECURITY_ATTRIBUTES* lpSecurityAttributes, FILE_CREATION_DISPOSITION dwCreationDisposition, FILE_FLAGS_AND_ATTRIBUTES dwFlagsAndAttributes, HANDLE hTemplateFile, HANDLE hTransaction, TXFS_MINIVERSION* pusMiniVersion, void* lpExtendedParameter)
#uselib "KERNEL32.dll"
#cfunc global CreateFileTransactedW "CreateFileTransactedW" wstr, int, int, var, int, int, intptr, intptr, var, intptr
; res = CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter)
; lpFileName : LPCWSTR -> "wstr"
; dwDesiredAccess : DWORD -> "int"
; dwShareMode : FILE_SHARE_MODE -> "int"
; lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> "var"
; dwCreationDisposition : FILE_CREATION_DISPOSITION -> "int"
; dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> "int"
; hTemplateFile : HANDLE optional -> "intptr"
; hTransaction : HANDLE -> "intptr"
; pusMiniVersion : TXFS_MINIVERSION* optional -> "var"
; lpExtendedParameter : void* optional -> "intptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procCreateFileTransactedW = kernel32.NewProc("CreateFileTransactedW")
)

// lpFileName (LPCWSTR), dwDesiredAccess (DWORD), dwShareMode (FILE_SHARE_MODE), lpSecurityAttributes (SECURITY_ATTRIBUTES* optional), dwCreationDisposition (FILE_CREATION_DISPOSITION), dwFlagsAndAttributes (FILE_FLAGS_AND_ATTRIBUTES), hTemplateFile (HANDLE optional), hTransaction (HANDLE), pusMiniVersion (TXFS_MINIVERSION* optional), lpExtendedParameter (void* optional)
r1, _, err := procCreateFileTransactedW.Call(
	uintptr(unsafe.Pointer(windows.StringToUTF16Ptr(lpFileName))),
	uintptr(dwDesiredAccess),
	uintptr(dwShareMode),
	uintptr(lpSecurityAttributes),
	uintptr(dwCreationDisposition),
	uintptr(dwFlagsAndAttributes),
	uintptr(hTemplateFile),
	uintptr(hTransaction),
	uintptr(pusMiniVersion),
	uintptr(lpExtendedParameter),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // HANDLE
function CreateFileTransactedW(
  lpFileName: PWideChar;   // LPCWSTR
  dwDesiredAccess: DWORD;   // DWORD
  dwShareMode: DWORD;   // FILE_SHARE_MODE
  lpSecurityAttributes: Pointer;   // SECURITY_ATTRIBUTES* optional
  dwCreationDisposition: DWORD;   // FILE_CREATION_DISPOSITION
  dwFlagsAndAttributes: DWORD;   // FILE_FLAGS_AND_ATTRIBUTES
  hTemplateFile: THandle;   // HANDLE optional
  hTransaction: THandle;   // HANDLE
  pusMiniVersion: Pointer;   // TXFS_MINIVERSION* optional
  lpExtendedParameter: Pointer   // void* optional
): THandle; stdcall;
  external 'KERNEL32.dll' name 'CreateFileTransactedW';
result := DllCall("KERNEL32\CreateFileTransactedW"
    , "WStr", lpFileName   ; LPCWSTR
    , "UInt", dwDesiredAccess   ; DWORD
    , "UInt", dwShareMode   ; FILE_SHARE_MODE
    , "Ptr", lpSecurityAttributes   ; SECURITY_ATTRIBUTES* optional
    , "UInt", dwCreationDisposition   ; FILE_CREATION_DISPOSITION
    , "UInt", dwFlagsAndAttributes   ; FILE_FLAGS_AND_ATTRIBUTES
    , "Ptr", hTemplateFile   ; HANDLE optional
    , "Ptr", hTransaction   ; HANDLE
    , "Ptr", pusMiniVersion   ; TXFS_MINIVERSION* optional
    , "Ptr", lpExtendedParameter   ; void* optional
    , "Ptr")   ; return: HANDLE
●CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter) = DLL("KERNEL32.dll", "void* CreateFileTransactedW(char*, dword, dword, void*, dword, dword, void*, void*, void*, void*)")
# 呼び出し: CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter)
# lpFileName : LPCWSTR -> "char*"
# dwDesiredAccess : DWORD -> "dword"
# dwShareMode : FILE_SHARE_MODE -> "dword"
# lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> "void*"
# dwCreationDisposition : FILE_CREATION_DISPOSITION -> "dword"
# dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> "dword"
# hTemplateFile : HANDLE optional -> "void*"
# hTransaction : HANDLE -> "void*"
# pusMiniVersion : TXFS_MINIVERSION* optional -> "void*"
# lpExtendedParameter : void* optional -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
# ※-W(Unicode)関数。なでしこ1はANSIのため -A 版の利用を推奨。
const std = @import("std");

extern "kernel32" fn CreateFileTransactedW(
    lpFileName: [*c]const u16, // LPCWSTR
    dwDesiredAccess: u32, // DWORD
    dwShareMode: u32, // FILE_SHARE_MODE
    lpSecurityAttributes: [*c]SECURITY_ATTRIBUTES, // SECURITY_ATTRIBUTES* optional
    dwCreationDisposition: u32, // FILE_CREATION_DISPOSITION
    dwFlagsAndAttributes: u32, // FILE_FLAGS_AND_ATTRIBUTES
    hTemplateFile: ?*anyopaque, // HANDLE optional
    hTransaction: ?*anyopaque, // HANDLE
    pusMiniVersion: [*c]u32, // TXFS_MINIVERSION* optional
    lpExtendedParameter: ?*anyopaque // void* optional
) callconv(std.os.windows.WINAPI) ?*anyopaque;
// Unicode(-W): UTF-16LE のヌル終端バッファ([*c]const u16)を渡す。
proc CreateFileTransactedW(
    lpFileName: WideCString,  # LPCWSTR
    dwDesiredAccess: uint32,  # DWORD
    dwShareMode: uint32,  # FILE_SHARE_MODE
    lpSecurityAttributes: ptr SECURITY_ATTRIBUTES,  # SECURITY_ATTRIBUTES* optional
    dwCreationDisposition: uint32,  # FILE_CREATION_DISPOSITION
    dwFlagsAndAttributes: uint32,  # FILE_FLAGS_AND_ATTRIBUTES
    hTemplateFile: pointer,  # HANDLE optional
    hTransaction: pointer,  # HANDLE
    pusMiniVersion: ptr uint32,  # TXFS_MINIVERSION* optional
    lpExtendedParameter: pointer  # void* optional
): pointer {.importc: "CreateFileTransactedW", stdcall, dynlib: "KERNEL32.dll".}
# Unicode(-W): WideCString は newWideCString("...") で生成。
pragma(lib, "kernel32");
extern(Windows)
void* CreateFileTransactedW(
    const(wchar)* lpFileName,   // LPCWSTR
    uint dwDesiredAccess,   // DWORD
    uint dwShareMode,   // FILE_SHARE_MODE
    SECURITY_ATTRIBUTES* lpSecurityAttributes,   // SECURITY_ATTRIBUTES* optional
    uint dwCreationDisposition,   // FILE_CREATION_DISPOSITION
    uint dwFlagsAndAttributes,   // FILE_FLAGS_AND_ATTRIBUTES
    void* hTemplateFile,   // HANDLE optional
    void* hTransaction,   // HANDLE
    uint* pusMiniVersion,   // TXFS_MINIVERSION* optional
    void* lpExtendedParameter   // void* optional
);
ccall((:CreateFileTransactedW, "KERNEL32.dll"), stdcall, Ptr{Cvoid},
      (Cwstring, UInt32, UInt32, Ptr{SECURITY_ATTRIBUTES}, UInt32, UInt32, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{UInt32}, Ptr{Cvoid}),
      lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter)
# lpFileName : LPCWSTR -> Cwstring
# dwDesiredAccess : DWORD -> UInt32
# dwShareMode : FILE_SHARE_MODE -> UInt32
# lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> Ptr{SECURITY_ATTRIBUTES}
# dwCreationDisposition : FILE_CREATION_DISPOSITION -> UInt32
# dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> UInt32
# hTemplateFile : HANDLE optional -> Ptr{Cvoid}
# hTransaction : HANDLE -> Ptr{Cvoid}
# pusMiniVersion : TXFS_MINIVERSION* optional -> Ptr{UInt32}
# lpExtendedParameter : void* optional -> Ptr{Cvoid}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
# Unicode(-W): Cwstring には transcode(UInt16, "...") 等で UTF-16 を渡す。
local ffi = require("ffi")
ffi.cdef[[
void* CreateFileTransactedW(
    const uint16_t* lpFileName,
    uint32_t dwDesiredAccess,
    uint32_t dwShareMode,
    void* lpSecurityAttributes,
    uint32_t dwCreationDisposition,
    uint32_t dwFlagsAndAttributes,
    void* hTemplateFile,
    void* hTransaction,
    uint32_t* pusMiniVersion,
    void* lpExtendedParameter);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter)
-- lpFileName : LPCWSTR
-- dwDesiredAccess : DWORD
-- dwShareMode : FILE_SHARE_MODE
-- lpSecurityAttributes : SECURITY_ATTRIBUTES* optional
-- dwCreationDisposition : FILE_CREATION_DISPOSITION
-- dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES
-- hTemplateFile : HANDLE optional
-- hTransaction : HANDLE
-- pusMiniVersion : TXFS_MINIVERSION* optional
-- lpExtendedParameter : void* optional
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
-- Unicode(-W): uint16_t* には UTF-16LE のバッファ(ffi.new("uint16_t[?]", ...))を渡す。
const koffi = require('koffi');
const lib = koffi.load('KERNEL32.dll');
const CreateFileTransactedW = lib.func('__stdcall', 'CreateFileTransactedW', 'void *', ['str16', 'uint32_t', 'uint32_t', 'void *', 'uint32_t', 'uint32_t', 'void *', 'void *', 'uint32_t *', 'void *']);
// CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter)
// lpFileName : LPCWSTR -> 'str16'
// dwDesiredAccess : DWORD -> 'uint32_t'
// dwShareMode : FILE_SHARE_MODE -> 'uint32_t'
// lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> 'void *'
// dwCreationDisposition : FILE_CREATION_DISPOSITION -> 'uint32_t'
// dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> 'uint32_t'
// hTemplateFile : HANDLE optional -> 'void *'
// hTransaction : HANDLE -> 'void *'
// pusMiniVersion : TXFS_MINIVERSION* optional -> 'uint32_t *'
// lpExtendedParameter : void* optional -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  CreateFileTransactedW: { parameters: ["buffer", "u32", "u32", "pointer", "u32", "u32", "pointer", "pointer", "pointer", "pointer"], result: "pointer" },
});
// lib.symbols.CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter)
// lpFileName : LPCWSTR -> "buffer"
// dwDesiredAccess : DWORD -> "u32"
// dwShareMode : FILE_SHARE_MODE -> "u32"
// lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> "pointer"
// dwCreationDisposition : FILE_CREATION_DISPOSITION -> "u32"
// dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> "u32"
// hTemplateFile : HANDLE optional -> "pointer"
// hTransaction : HANDLE -> "pointer"
// pusMiniVersion : TXFS_MINIVERSION* optional -> "pointer"
// lpExtendedParameter : void* optional -> "pointer"
// 文字列は "buffer"。Unicode(-W) は new TextEncoder() ではなく UTF-16LE のバイト列(末尾に \x00\x00)を Uint8Array で渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
void* CreateFileTransactedW(
    const uint16_t* lpFileName,
    uint32_t dwDesiredAccess,
    uint32_t dwShareMode,
    void* lpSecurityAttributes,
    uint32_t dwCreationDisposition,
    uint32_t dwFlagsAndAttributes,
    void* hTemplateFile,
    void* hTransaction,
    uint32_t* pusMiniVersion,
    void* lpExtendedParameter);
C, "KERNEL32.dll");
// $ffi->CreateFileTransactedW(lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter);
// lpFileName : LPCWSTR
// dwDesiredAccess : DWORD
// dwShareMode : FILE_SHARE_MODE
// lpSecurityAttributes : SECURITY_ATTRIBUTES* optional
// dwCreationDisposition : FILE_CREATION_DISPOSITION
// dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES
// hTemplateFile : HANDLE optional
// hTransaction : HANDLE
// pusMiniVersion : TXFS_MINIVERSION* optional
// lpExtendedParameter : void* optional
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Kernel32 extends StdCallLibrary {
    Kernel32 INSTANCE = Native.load("kernel32", Kernel32.class, W32APIOptions.UNICODE_OPTIONS);
    Pointer CreateFileTransactedW(
        WString lpFileName,   // LPCWSTR
        int dwDesiredAccess,   // DWORD
        int dwShareMode,   // FILE_SHARE_MODE
        Pointer lpSecurityAttributes,   // SECURITY_ATTRIBUTES* optional
        int dwCreationDisposition,   // FILE_CREATION_DISPOSITION
        int dwFlagsAndAttributes,   // FILE_FLAGS_AND_ATTRIBUTES
        Pointer hTemplateFile,   // HANDLE optional
        Pointer hTransaction,   // HANDLE
        IntByReference pusMiniVersion,   // TXFS_MINIVERSION* optional
        Pointer lpExtendedParameter   // void* optional
    );
}
// Unicode(-W): WString(入力)/char[](出力)で UTF-16 をマーシャリング。
@[Link("kernel32")]
lib LibKERNEL32
  fun CreateFileTransactedW = CreateFileTransactedW(
    lpFileName : UInt16*,   # LPCWSTR
    dwDesiredAccess : UInt32,   # DWORD
    dwShareMode : UInt32,   # FILE_SHARE_MODE
    lpSecurityAttributes : SECURITY_ATTRIBUTES*,   # SECURITY_ATTRIBUTES* optional
    dwCreationDisposition : UInt32,   # FILE_CREATION_DISPOSITION
    dwFlagsAndAttributes : UInt32,   # FILE_FLAGS_AND_ATTRIBUTES
    hTemplateFile : Void*,   # HANDLE optional
    hTransaction : Void*,   # HANDLE
    pusMiniVersion : UInt32*,   # TXFS_MINIVERSION* optional
    lpExtendedParameter : Void*   # void* optional
  ) : Void*
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef CreateFileTransactedWNative = Pointer<Void> Function(Pointer<Utf16>, Uint32, Uint32, Pointer<Void>, Uint32, Uint32, Pointer<Void>, Pointer<Void>, Pointer<Uint32>, Pointer<Void>);
typedef CreateFileTransactedWDart = Pointer<Void> Function(Pointer<Utf16>, int, int, Pointer<Void>, int, int, Pointer<Void>, Pointer<Void>, Pointer<Uint32>, Pointer<Void>);
final CreateFileTransactedW = DynamicLibrary.open('KERNEL32.dll')
    .lookupFunction<CreateFileTransactedWNative, CreateFileTransactedWDart>('CreateFileTransactedW');
// lpFileName : LPCWSTR -> Pointer<Utf16>
// dwDesiredAccess : DWORD -> Uint32
// dwShareMode : FILE_SHARE_MODE -> Uint32
// lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> Pointer<Void>
// dwCreationDisposition : FILE_CREATION_DISPOSITION -> Uint32
// dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> Uint32
// hTemplateFile : HANDLE optional -> Pointer<Void>
// hTransaction : HANDLE -> Pointer<Void>
// pusMiniVersion : TXFS_MINIVERSION* optional -> Pointer<Uint32>
// lpExtendedParameter : void* optional -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function CreateFileTransactedW(
  lpFileName: PWideChar;   // LPCWSTR
  dwDesiredAccess: DWORD;   // DWORD
  dwShareMode: DWORD;   // FILE_SHARE_MODE
  lpSecurityAttributes: Pointer;   // SECURITY_ATTRIBUTES* optional
  dwCreationDisposition: DWORD;   // FILE_CREATION_DISPOSITION
  dwFlagsAndAttributes: DWORD;   // FILE_FLAGS_AND_ATTRIBUTES
  hTemplateFile: THandle;   // HANDLE optional
  hTransaction: THandle;   // HANDLE
  pusMiniVersion: Pointer;   // TXFS_MINIVERSION* optional
  lpExtendedParameter: Pointer   // void* optional
): THandle; stdcall;
  external 'KERNEL32.dll' name 'CreateFileTransactedW';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "CreateFileTransactedW"
  c_CreateFileTransactedW :: CWString -> Word32 -> Word32 -> Ptr () -> Word32 -> Word32 -> Ptr () -> Ptr () -> Ptr Word32 -> Ptr () -> IO (Ptr ())
-- lpFileName : LPCWSTR -> CWString
-- dwDesiredAccess : DWORD -> Word32
-- dwShareMode : FILE_SHARE_MODE -> Word32
-- lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> Ptr ()
-- dwCreationDisposition : FILE_CREATION_DISPOSITION -> Word32
-- dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> Word32
-- hTemplateFile : HANDLE optional -> Ptr ()
-- hTransaction : HANDLE -> Ptr ()
-- pusMiniVersion : TXFS_MINIVERSION* optional -> Ptr Word32
-- lpExtendedParameter : void* optional -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let createfiletransactedw =
  foreign "CreateFileTransactedW"
    ((ptr uint16_t) @-> uint32_t @-> uint32_t @-> (ptr void) @-> uint32_t @-> uint32_t @-> (ptr void) @-> (ptr void) @-> (ptr uint32_t) @-> (ptr void) @-> returning (ptr void))
(* lpFileName : LPCWSTR -> (ptr uint16_t) *)
(* dwDesiredAccess : DWORD -> uint32_t *)
(* dwShareMode : FILE_SHARE_MODE -> uint32_t *)
(* lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> (ptr void) *)
(* dwCreationDisposition : FILE_CREATION_DISPOSITION -> uint32_t *)
(* dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> uint32_t *)
(* hTemplateFile : HANDLE optional -> (ptr void) *)
(* hTransaction : HANDLE -> (ptr void) *)
(* pusMiniVersion : TXFS_MINIVERSION* optional -> (ptr uint32_t) *)
(* lpExtendedParameter : void* optional -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library kernel32 (t "KERNEL32.dll"))
(cffi:use-foreign-library kernel32)

(cffi:defcfun ("CreateFileTransactedW" create-file-transacted-w :convention :stdcall) :pointer
  (lp-file-name (:string :encoding :utf-16le))   ; LPCWSTR
  (dw-desired-access :uint32)   ; DWORD
  (dw-share-mode :uint32)   ; FILE_SHARE_MODE
  (lp-security-attributes :pointer)   ; SECURITY_ATTRIBUTES* optional
  (dw-creation-disposition :uint32)   ; FILE_CREATION_DISPOSITION
  (dw-flags-and-attributes :uint32)   ; FILE_FLAGS_AND_ATTRIBUTES
  (h-template-file :pointer)   ; HANDLE optional
  (h-transaction :pointer)   ; HANDLE
  (pus-mini-version :pointer)   ; TXFS_MINIVERSION* optional
  (lp-extended-parameter :pointer))   ; void* optional
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $CreateFileTransactedW = Win32::API::More->new('KERNEL32',
    'HANDLE CreateFileTransactedW(LPCWSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, LPVOID lpSecurityAttributes, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes, HANDLE hTemplateFile, HANDLE hTransaction, LPVOID pusMiniVersion, LPVOID lpExtendedParameter)');
# my $ret = $CreateFileTransactedW->Call($lpFileName, $dwDesiredAccess, $dwShareMode, $lpSecurityAttributes, $dwCreationDisposition, $dwFlagsAndAttributes, $hTemplateFile, $hTransaction, $pusMiniVersion, $lpExtendedParameter);
# lpFileName : LPCWSTR -> LPCWSTR
# dwDesiredAccess : DWORD -> DWORD
# dwShareMode : FILE_SHARE_MODE -> DWORD
# lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> LPVOID
# dwCreationDisposition : FILE_CREATION_DISPOSITION -> DWORD
# dwFlagsAndAttributes : FILE_FLAGS_AND_ATTRIBUTES -> DWORD
# hTemplateFile : HANDLE optional -> HANDLE
# hTransaction : HANDLE -> HANDLE
# pusMiniVersion : TXFS_MINIVERSION* optional -> LPVOID
# lpExtendedParameter : void* optional -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# Unicode(-W): LPCWSTR/LPWSTR は Win32::API が UTF-16 変換を行う。

関連項目

文字セット違い
公式の関連項目
使用する型