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

SetFileAttributesTransactedA

関数
トランザクション内でファイル属性を設定する(ANSI版)。
DLLKERNEL32.dll文字セットANSI (-A)呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

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

パラメーター

名前方向説明
lpFileNameLPCSTRin

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

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

ヒント

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

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

dwFileAttributesDWORDin

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

ファイル属性の値とその説明の一覧については、 File Attribute Constants を参照してください。このパラメーターには、ビットごとの 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))

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

戻り値の型: BOOL

公式ドキュメント

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

戻り値

関数が成功した場合、戻り値は 0 以外の値です。

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

解説(Remarks)

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

属性 設定方法
FILE_ATTRIBUTE_COMPRESSED

0x800

ファイルの圧縮状態を設定するには、 DeviceIoControl 関数を FSCTL_SET_COMPRESSION 操作とともに使用します。
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

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

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

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

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

テクノロジ サポート
Server Message Block (SMB) 3.0 プロトコル いいえ
SMB 3.0 透過的フェールオーバー (TFO) いいえ
SMB 3.0 スケールアウトファイル共有 (SO) いいえ
クラスター共有ボリュームファイルシステム (CsvFS) いいえ
回復性ファイルシステム (ReFS) いいえ

SMB 3.0 は TxF をサポートしていません。

トランザクション操作

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

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

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

各言語での呼び出し定義

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

BOOL SetFileAttributesTransactedA(
    LPCSTR lpFileName,
    DWORD dwFileAttributes,
    HANDLE hTransaction
);
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern bool SetFileAttributesTransactedA(
    [MarshalAs(UnmanagedType.LPStr)] string lpFileName,   // LPCSTR
    uint dwFileAttributes,   // DWORD
    IntPtr hTransaction   // HANDLE
);
<DllImport("KERNEL32.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function SetFileAttributesTransactedA(
    <MarshalAs(UnmanagedType.LPStr)> lpFileName As String,   ' LPCSTR
    dwFileAttributes As UInteger,   ' DWORD
    hTransaction As IntPtr   ' HANDLE
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
' lpFileName : LPCSTR
' dwFileAttributes : DWORD
' hTransaction : HANDLE
Declare PtrSafe Function SetFileAttributesTransactedA Lib "kernel32" ( _
    ByVal lpFileName As String, _
    ByVal dwFileAttributes As Long, _
    ByVal hTransaction As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

SetFileAttributesTransactedA = ctypes.windll.kernel32.SetFileAttributesTransactedA
SetFileAttributesTransactedA.restype = wintypes.BOOL
SetFileAttributesTransactedA.argtypes = [
    wintypes.LPCSTR,  # lpFileName : LPCSTR
    wintypes.DWORD,  # dwFileAttributes : DWORD
    wintypes.HANDLE,  # hTransaction : HANDLE
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
SetFileAttributesTransactedA = Fiddle::Function.new(
  lib['SetFileAttributesTransactedA'],
  [
    Fiddle::TYPE_VOIDP,  # lpFileName : LPCSTR
    -Fiddle::TYPE_INT,  # dwFileAttributes : DWORD
    Fiddle::TYPE_VOIDP,  # hTransaction : HANDLE
  ],
  Fiddle::TYPE_INT)
#[link(name = "kernel32")]
extern "system" {
    fn SetFileAttributesTransactedA(
        lpFileName: *const u8,  // LPCSTR
        dwFileAttributes: u32,  // DWORD
        hTransaction: *mut core::ffi::c_void  // HANDLE
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern bool SetFileAttributesTransactedA([MarshalAs(UnmanagedType.LPStr)] string lpFileName, uint dwFileAttributes, IntPtr hTransaction);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_SetFileAttributesTransactedA' -Namespace Win32 -PassThru
# $api::SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction)
#uselib "KERNEL32.dll"
#func global SetFileAttributesTransactedA "SetFileAttributesTransactedA" sptr, sptr, sptr
; SetFileAttributesTransactedA lpFileName, dwFileAttributes, hTransaction   ; 戻り値は stat
; lpFileName : LPCSTR -> "sptr"
; dwFileAttributes : DWORD -> "sptr"
; hTransaction : HANDLE -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "KERNEL32.dll"
#cfunc global SetFileAttributesTransactedA "SetFileAttributesTransactedA" str, int, sptr
; res = SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction)
; lpFileName : LPCSTR -> "str"
; dwFileAttributes : DWORD -> "int"
; hTransaction : HANDLE -> "sptr"
; BOOL SetFileAttributesTransactedA(LPCSTR lpFileName, DWORD dwFileAttributes, HANDLE hTransaction)
#uselib "KERNEL32.dll"
#cfunc global SetFileAttributesTransactedA "SetFileAttributesTransactedA" str, int, intptr
; res = SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction)
; lpFileName : LPCSTR -> "str"
; dwFileAttributes : DWORD -> "int"
; hTransaction : HANDLE -> "intptr"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procSetFileAttributesTransactedA = kernel32.NewProc("SetFileAttributesTransactedA")
)

// lpFileName (LPCSTR), dwFileAttributes (DWORD), hTransaction (HANDLE)
r1, _, err := procSetFileAttributesTransactedA.Call(
	uintptr(unsafe.Pointer(windows.BytePtrFromString(lpFileName))),
	uintptr(dwFileAttributes),
	uintptr(hTransaction),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // BOOL
function SetFileAttributesTransactedA(
  lpFileName: PAnsiChar;   // LPCSTR
  dwFileAttributes: DWORD;   // DWORD
  hTransaction: THandle   // HANDLE
): BOOL; stdcall;
  external 'KERNEL32.dll' name 'SetFileAttributesTransactedA';
result := DllCall("KERNEL32\SetFileAttributesTransactedA"
    , "AStr", lpFileName   ; LPCSTR
    , "UInt", dwFileAttributes   ; DWORD
    , "Ptr", hTransaction   ; HANDLE
    , "Int")   ; return: BOOL
●SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction) = DLL("KERNEL32.dll", "bool SetFileAttributesTransactedA(char*, dword, void*)")
# 呼び出し: SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction)
# lpFileName : LPCSTR -> "char*"
# dwFileAttributes : DWORD -> "dword"
# hTransaction : HANDLE -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "kernel32" fn SetFileAttributesTransactedA(
    lpFileName: [*c]const u8, // LPCSTR
    dwFileAttributes: u32, // DWORD
    hTransaction: ?*anyopaque // HANDLE
) callconv(std.os.windows.WINAPI) i32;
proc SetFileAttributesTransactedA(
    lpFileName: cstring,  # LPCSTR
    dwFileAttributes: uint32,  # DWORD
    hTransaction: pointer  # HANDLE
): int32 {.importc: "SetFileAttributesTransactedA", stdcall, dynlib: "KERNEL32.dll".}
pragma(lib, "kernel32");
extern(Windows)
int SetFileAttributesTransactedA(
    const(char)* lpFileName,   // LPCSTR
    uint dwFileAttributes,   // DWORD
    void* hTransaction   // HANDLE
);
ccall((:SetFileAttributesTransactedA, "KERNEL32.dll"), stdcall, Int32,
      (Cstring, UInt32, Ptr{Cvoid}),
      lpFileName, dwFileAttributes, hTransaction)
# lpFileName : LPCSTR -> Cstring
# dwFileAttributes : DWORD -> UInt32
# hTransaction : HANDLE -> Ptr{Cvoid}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int32_t SetFileAttributesTransactedA(
    const char* lpFileName,
    uint32_t dwFileAttributes,
    void* hTransaction);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction)
-- lpFileName : LPCSTR
-- dwFileAttributes : DWORD
-- hTransaction : HANDLE
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('KERNEL32.dll');
const SetFileAttributesTransactedA = lib.func('__stdcall', 'SetFileAttributesTransactedA', 'int32_t', ['str', 'uint32_t', 'void *']);
// SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction)
// lpFileName : LPCSTR -> 'str'
// dwFileAttributes : DWORD -> 'uint32_t'
// hTransaction : HANDLE -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  SetFileAttributesTransactedA: { parameters: ["buffer", "u32", "pointer"], result: "i32" },
});
// lib.symbols.SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction)
// lpFileName : LPCSTR -> "buffer"
// dwFileAttributes : DWORD -> "u32"
// hTransaction : HANDLE -> "pointer"
// 文字列は "buffer"。ANSI(-A) は new TextEncoder() で UTF-8/ANSI バイト列(末尾に \x00)を渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t SetFileAttributesTransactedA(
    const char* lpFileName,
    uint32_t dwFileAttributes,
    void* hTransaction);
C, "KERNEL32.dll");
// $ffi->SetFileAttributesTransactedA(lpFileName, dwFileAttributes, hTransaction);
// lpFileName : LPCSTR
// dwFileAttributes : DWORD
// hTransaction : HANDLE
// 構造体/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.ASCII_OPTIONS);
    boolean SetFileAttributesTransactedA(
        String lpFileName,   // LPCSTR
        int dwFileAttributes,   // DWORD
        Pointer hTransaction   // HANDLE
    );
}
@[Link("kernel32")]
lib LibKERNEL32
  fun SetFileAttributesTransactedA = SetFileAttributesTransactedA(
    lpFileName : UInt8*,   # LPCSTR
    dwFileAttributes : UInt32,   # DWORD
    hTransaction : Void*   # HANDLE
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef SetFileAttributesTransactedANative = Int32 Function(Pointer<Utf8>, Uint32, Pointer<Void>);
typedef SetFileAttributesTransactedADart = int Function(Pointer<Utf8>, int, Pointer<Void>);
final SetFileAttributesTransactedA = DynamicLibrary.open('KERNEL32.dll')
    .lookupFunction<SetFileAttributesTransactedANative, SetFileAttributesTransactedADart>('SetFileAttributesTransactedA');
// lpFileName : LPCSTR -> Pointer<Utf8>
// dwFileAttributes : DWORD -> Uint32
// hTransaction : HANDLE -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function SetFileAttributesTransactedA(
  lpFileName: PAnsiChar;   // LPCSTR
  dwFileAttributes: DWORD;   // DWORD
  hTransaction: THandle   // HANDLE
): BOOL; stdcall;
  external 'KERNEL32.dll' name 'SetFileAttributesTransactedA';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "SetFileAttributesTransactedA"
  c_SetFileAttributesTransactedA :: CString -> Word32 -> Ptr () -> IO CInt
-- lpFileName : LPCSTR -> CString
-- dwFileAttributes : DWORD -> Word32
-- hTransaction : HANDLE -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let setfileattributestransacteda =
  foreign "SetFileAttributesTransactedA"
    (string @-> uint32_t @-> (ptr void) @-> returning int32_t)
(* lpFileName : LPCSTR -> string *)
(* dwFileAttributes : DWORD -> uint32_t *)
(* hTransaction : HANDLE -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library kernel32 (t "KERNEL32.dll"))
(cffi:use-foreign-library kernel32)

(cffi:defcfun ("SetFileAttributesTransactedA" set-file-attributes-transacted-a :convention :stdcall) :int32
  (lp-file-name :string)   ; LPCSTR
  (dw-file-attributes :uint32)   ; DWORD
  (h-transaction :pointer))   ; HANDLE
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $SetFileAttributesTransactedA = Win32::API::More->new('KERNEL32',
    'BOOL SetFileAttributesTransactedA(LPCSTR lpFileName, DWORD dwFileAttributes, HANDLE hTransaction)');
# my $ret = $SetFileAttributesTransactedA->Call($lpFileName, $dwFileAttributes, $hTransaction);
# lpFileName : LPCSTR -> LPCSTR
# dwFileAttributes : DWORD -> DWORD
# hTransaction : HANDLE -> HANDLE
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

文字セット違い
公式の関連項目