SetFileAttributesTransactedA 関数 (winbase.h)

  • [アーティクル]

[Microsoft では、開発者がアプリケーションのニーズを達成するために代替手段を利用することを強くお勧めします。 TxF が開発された多くのシナリオは、よりシンプルで利用しやすい手法で実現できます。 また、将来のバージョンの Microsoft Windows では TxF を使用できない場合があります。 詳細、および TxF の代替手段については、「トランザクション NTFS の使用の代替手段」を参照してください。]

トランザクション操作として、ファイルまたはディレクトリの属性を設定します。

構文

BOOL SetFileAttributesTransactedA(
  [in] LPCSTR lpFileName,
  [in] DWORD  dwFileAttributes,
  [in] HANDLE hTransaction
);

パラメーター

[in] lpFileName

属性を設定するファイルの名前。

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

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前もって指定しなくても、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 名前付けファイル、パス、および名前空間 」の「パスの最大長制限」セクションを参照してください。

ファイルはローカル コンピューター上に存在する必要があります。それ以外の場合、関数は失敗し、最後のエラー コードは ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE に設定されます。

[in] dwFileAttributes

ファイルに設定するファイル属性。

ファイル属性値とその説明の一覧については、「 ファイル属性定数」を参照してください。 このパラメーターには、ビットごとの OR 演算子を使用して組み合わせた 1 つ以上の値を指定できます。 ただし、他のすべての値 はFILE_ATTRIBUTE_NORMALをオーバーライドします。

この関数では、すべての属性がサポートされているわけではありません。 詳細については、「解説」を参照してください。

サポートされている属性値の一覧を次に示します。

FILE_ATTRIBUTE_ARCHIVE (32 (0x20))

FILE_ATTRIBUTE_HIDDEN (2 (0x2))

FILE_ATTRIBUTE_NORMAL (128 (0x80))

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (8192 (0x2000))

FILE_ATTRIBUTE_OFFLINE (4096 (0x1000))

FILE_ATTRIBUTE_READONLY (1 (0x1))

FILE_ATTRIBUTE_SYSTEM (4 (0x4))

FILE_ATTRIBUTE_TEMPORARY (256 (0x100))

[in] hTransaction

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

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

次の表では、 SetFileAttributesTransacted を使用して設定できない属性を設定する方法について説明します。 これらはトランザクション操作ではないことに注意してください。

属性 設定方法
FILE_ATTRIBUTE_COMPRESSED

0x800

 ファイルの圧縮状態を設定するには、FSCTL_SET_COMPRESSION操作で DeviceIoControl 関数を使用します。
FILE_ATTRIBUTE_DEVICE

0x40

 予約済みです。使わないでください。
FILE_ATTRIBUTE_DIRECTORY

0x10

 ファイルをディレクトリに変換することはできません。 ディレクトリを作成するには、 CreateDirectory または CreateDirectoryEx 関数 を 使用します。
FILE_ATTRIBUTE_ENCRYPTED

0x4000

 暗号化されたファイルを作成するには、 CreateFile 関数と FILE_ATTRIBUTE_ENCRYPTED 属性を使用します。 既存のファイルを暗号化されたファイルに変換するには、 EncryptFile 関数を使用します。
FILE_ATTRIBUTE_REPARSE_POINT

0x400

 再解析ポイントをファイルまたはディレクトリに関連付けるには、 DeviceIoControl 関数と FSCTL_SET_REPARSE_POINT 操作を使用します。
FILE_ATTRIBUTE_SPARSE_FILE

0x200

 ファイルのスパース属性を設定するには、FSCTL_SET_SPARSE操作で DeviceIoControl 関数を使用します。
 

ファイルがトランザクションで変更のために開かれている場合、トランザクションがコミットされるまで、他のスレッドはファイルを正常に開いて変更できません。 トランザクションスレッドが最初にファイルを開いた場合、トランザクションがコミットされる前に変更のためにファイルを開こうとした後続のスレッドは、共有違反を受け取ります。 トランザクションされていないスレッドがトランザクションスレッドの前に変更のためにファイルを開き、トランザクションスレッドが開こうとしたときに開いている場合、トランザクションは ERROR_TRANSACTIONAL_CONFLICT エラーを受け取ります。

トランザクションの詳細については、「 トランザクション NTFS」を参照してください。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル いいえ
SMB 3.0 Transparent Failover (TFO) いいえ
スケールアウト ファイル共有 (SO) を使う SMB 3.0 いいえ
クラスターの共有ボリューム ファイル システム (CsvFS) いいえ
Resilient File System (ReFS) いいえ
 

SMB 3.0 では TxF はサポートされていません。

Transacted Operations

ファイルがトランザクションで変更のために開かれている場合、トランザクションがコミットされるまで、他のスレッドは変更のためにファイルを開くできません。 そのため、トランザクションスレッドが最初にファイルを開くと、トランザクションがコミットされる前にファイルを変更しようとする後続のスレッドは共有違反を受け取ります。 トランザクション以外のスレッドがトランザクションスレッドの前にファイルを変更しても、トランザクションが開こうとしたときにファイルが開いている場合、トランザクションはエラー ERROR_TRANSACTIONAL_CONFLICTを受け取ります。

注意

winbase.h ヘッダーは、SetFileAttributesTransacted をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

ファイル属性定数

File Management 関数

GetFileAttributesTransacted

シンボリック リンク

トランザクション NTFS