CreateFileTransactedW

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

CreateFileTransactedW lpFileName, dwDesiredAccess, dwShareMode, lpSecurityAttributes, dwCreationDisposition, dwFlagsAndAttributes, hTemplateFile, hTransaction, pusMiniVersion, lpExtendedParameter

lpFileName : [wstr] 作成または開くオブジェクトの名前。オブジェクトはローカルコンピュータ上に存在しなければならない。そうでない場合、関数は失敗し最終エラーコードは ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE に設定される。この関数の ANSI 版では、名前は MAX_PATH 文字に制限されている。この制限を 32,767 ワイド文字まで拡張するには、Unicode 版を呼びパスの先頭に "\\?\" を付ける。詳細は Naming a File を参照。特殊なデバイス名については Defining an MS-DOS Device Name を参照。ファイルストリームを作成するには、ファイル名、コロン、ストリーム名の順に指定する。詳細は File Streams を参照。
dwDesiredAccess : [int] オブジェクトへのアクセス。読み取り、書き込み、両方、またはどちらでもない（ゼロ）にまとめられる。最も一般的に使われる値は GENERIC_READ、GENERIC_WRITE、またはその両方 (GENERIC_READ | GENERIC_WRITE) である。詳細は Generic Access Rights と File Security and Access Rights を参照。このパラメータがゼロの場合、アプリケーションはファイルやデバイスにアクセスせずに、ファイル、ディレクトリ、デバイスの属性を問い合わせることができる。詳細はこのトピックの備考を参照。開いているハンドルを持つ既存の open 要求で指定された共有モードと競合するアクセスモードを要求することはできない。詳細は Creating and Opening Files を参照。
dwShareMode : [int] オブジェクトの共有モード。読み取り、書き込み、両方、削除、これらすべて、またはどれでもない（以下の表を参照）が指定できる。このパラメータがゼロで CreateFileTransacted が成功した場合、オブジェクトは共有できず、ハンドルが閉じられるまで再度開けない。詳細はこのトピックの備考を参照。開いているハンドルを持つ既存の open 要求で指定されたアクセスモードと競合する共有モードを要求することはできない。要求した場合、ERROR_SHARING_VIOLATION の共有違反となる。詳細は Creating and Opening Files を参照。プロセスが別のプロセスがオブジェクトを開いている間にオブジェクトを共有できるようにするには、次のいずれか 1 つ以上を組み合わせて使う。
lpSecurityAttributes : [var] 省略可能なセキュリティ記述子を含み、返されるハンドルが子プロセスに継承可能かどうかを決定する SECURITY_ATTRIBUTES 構造体へのポインタ。このパラメータは NULL でも構わない。lpSecurityAttributes パラメータが NULL の場合、CreateFileTransacted から返されたハンドルはアプリケーションが作成する子プロセスに継承されず、返されたハンドルに関連付けられたオブジェクトには既定のセキュリティ記述子が付与される。構造体の bInheritHandle メンバーは返されたハンドルが継承可能かどうかを指定する。構造体の lpSecurityDescriptor メンバーはオブジェクトのセキュリティ記述子を指定するが、NULL でも構わない。lpSecurityDescriptor メンバーが NULL の場合、返されたハンドルに関連付けられたオブジェクトには既定のセキュリティ記述子が割り当てられる。既存ファイルを開くとき、CreateFileTransacted は lpSecurityDescriptor メンバーを無視するが、bInheritHandle メンバーは引き続き使用する。詳細はこのトピックの備考を参照。
dwCreationDisposition : [int] 存在するか存在しないファイルに対して行う動作。詳細はこのトピックの備考を参照。
dwFlagsAndAttributes : [int] ファイル属性とフラグ。最も一般的な既定値は 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 を参照。
hTemplateFile : [intptr] GENERIC_READ アクセス権を持つテンプレートファイルの有効なハンドル。テンプレートファイルは作成されるファイルにファイル属性と拡張属性を提供する。このパラメータは NULL でも構わない。既存ファイルを開くときは CreateFileTransacted がテンプレートファイルを無視する。新しい EFS 暗号化ファイルを開くとき、ファイルは親ディレクトリから DACL を継承する。
hTransaction : [intptr] トランザクションへのハンドル。このハンドルは CreateTransaction 関数が返す。
pusMiniVersion : [var] 開くミニバージョン。hTransaction で指定されたトランザクションがファイルを変更しているトランザクションでない場合、このパラメータは NULL であるべきである。そうでない場合、このパラメータには FSCTL_TXFS_CREATE_MINIVERSION 制御が返したミニバージョン識別子を指定できる。
lpExtendedParameter : [intptr] このパラメータは予約済みであり、NULL でなければならない。

(プラグイン / モジュール : kernel32.dll)

解説

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

[戻り値]

関数が成功した場合、戻り値は指定されたファイル、デバイス、名前付きパイプ、またはメールスロットへの開かれたハンドル。関数が失敗した場合、戻り値は
INVALID_HANDLE_VALUE。拡張エラー情報を取得するには GetLastError を呼ぶ。

[備考]
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 が失敗することを意味する。非トランザクション対応アプリケーションが
lpSecurityAttributes に MAXIMUM_ALLOWED を指定して CreateFileTransacted
を呼ぶと、ハンドルは常に同じアクセスレベルで開かれる。トランザクション対応アプリケーションが lpSecurityAttributes に
MAXIMUM_ALLOWED を指定して CreateFileTransacted
を呼ぶと、ファイルがトランザクションによってロックされているかどうかに応じて異なる量のアクセスでハンドルが開かれる。例えば、呼び出し側アプリケーションがファイルに対して
FILE_EXECUTE
アクセスレベルを持っている場合、そのファイルがトランザクションによってロックされていないか、そのファイルがトランザクションによってロックされておりアプリケーションが既にそのファイルのトランザクション読み取り側である場合にのみ、このアクセスが得られる。トランザクション操作の完全な説明は
Transactional NTFS を参照。CreateFileTransacted
から返されたオブジェクトハンドルが不要になり、トランザクションのコミットまたはロールバックの前に閉じるには CloseHandle
関数を使う。NTFS
ファイルシステムのような一部のファイルシステムは個々のファイルとディレクトリの圧縮または暗号化をサポートしている。そのようなファイルシステムでフォーマットされたボリュームでは、新しいファイルは親ディレクトリの圧縮と暗号化の属性を継承する。CreateFileTransacted
を使ってファイルやディレクトリの圧縮を制御することはできない。詳細は File Compression and Decompression
および File Encryption を参照。シンボリックリンクの動作 ?
この関数の呼び出しが新しいファイルを作成する場合、動作に変更はない。FILE_FLAG_OPEN_REPARSE_POINT
が指定された場合:
（以下省略）

情報