ホーム › Storage.FileSystem › CreateHardLinkTransactedW

CreateHardLinkTransactedW

関数

トランザクション内でハードリンクを作成する(Unicode版)。

DLLKERNEL32.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

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

BOOL CreateHardLinkTransactedW(
    LPCWSTR lpFileName,
    LPCWSTR lpExistingFileName,
    SECURITY_ATTRIBUTES* lpSecurityAttributes,   // optional
    HANDLE hTransaction
);

パラメーター

名前	型	方向	説明
lpFileName	LPCWSTR	in	新しいファイルの名前。このパラメーターでディレクトリの名前を指定することはできません。
lpExistingFileName	LPCWSTR	in	既存のファイルの名前。このパラメーターでディレクトリの名前を指定することはできません。
lpSecurityAttributes	SECURITY_ATTRIBUTES*	optional	予約済み。NULL を指定する必要があります。
hTransaction	HANDLE	in	トランザクションへのハンドル。このハンドルは CreateTransaction 関数によって返されます。

戻り値の型: BOOL

公式ドキュメント

既存のファイルと新しいファイルとの間にハードリンクを、トランザクション操作として確立します。(Unicode)

戻り値

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

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

この関数で作成できるハードリンクの最大数は、ファイルごとに 1023 個です。1 つのファイルに対して 1023 個を超えるリンクを作成しようとすると、エラーが発生します。

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

解説(Remarks)

CreateFileTransacted または CreateHardLinkTransacted で作成されたファイルのディレクトリエントリは、関連付けられたファイルへのハードリンクです。CreateHardLinkTransacted 関数で作成される追加のハードリンクを利用すると、 1 つのファイルに対して複数のディレクトリエントリ、つまり同一ファイルへの複数のハードリンクを持つことができます。これらは同じディレクトリ内で異なる名前にすることも、異なるディレクトリ内で同じまたは異なる名前にすることもできます。ただし、あるファイルへのすべてのハードリンクは同じボリューム上に存在する必要があります。

ハードリンクはファイルのディレクトリエントリにすぎないため、アプリケーションがいずれかのハードリンクを通じてファイルを変更すると、そのファイルへの他のハードリンクを使用するすべてのアプリケーションにその変更が反映されます。また、ファイルが変更されると、すべてのディレクトリエントリが更新されます。たとえば、ファイルサイズが変化すると、そのファイルへのすべてのハードリンクに新しいファイルサイズが表示されます。

セキュリティ記述子は、ハードリンクが指すファイルに属します。リンク自体はディレクトリエントリにすぎず、セキュリティ記述子を持ちません。したがって、ハードリンクのセキュリティ記述子を変更すると、基になるファイルのセキュリティ記述子を変更することになり、そのファイルを指すすべてのハードリンクが新しく指定されたアクセスを許可するようになります。ハードリンクごとに異なるセキュリティ記述子をファイルに付与することはできません。

この関数は、lpSecurityAttributes パラメーターでセキュリティ記述子の情報が渡された場合でも、リンク先のファイルのセキュリティ記述子を変更しません。

ハードリンクを削除するには DeleteFileTransacted を使用します。作成された順序にかかわらず、任意の順序で削除できます。

CreateFileTransacted で指定されたフラグ、属性、アクセス、共有は、ファイル単位で動作します。つまり、共有を許可しないファイルを開いた場合、別のアプリケーションがそのファイルへの新しいハードリンクを作成して共有することはできません。

NTFS ファイルシステム上でハードリンクを作成する場合、ディレクトリエントリ内のファイル属性情報は、ファイルが開かれたとき、または特定のファイルのハンドルを指定して GetFileInformationByHandle が呼び出されたときにのみ更新されます。

シンボリックリンク: パスがシンボリックリンクを指している場合、この関数はそのターゲットへのハードリンクを作成します。

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 をサポートしていないことに注意してください。

メモ

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

出典・ライセンス: 上記「公式ドキュメント」の内容は 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>

BOOL CreateHardLinkTransactedW(
    LPCWSTR lpFileName,
    LPCWSTR lpExistingFileName,
    SECURITY_ATTRIBUTES* lpSecurityAttributes,   // optional
    HANDLE hTransaction
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern bool CreateHardLinkTransactedW(
    [MarshalAs(UnmanagedType.LPWStr)] string lpFileName,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string lpExistingFileName,   // LPCWSTR
    IntPtr lpSecurityAttributes,   // SECURITY_ATTRIBUTES* optional
    IntPtr hTransaction   // HANDLE
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CreateHardLinkTransactedW(
    <MarshalAs(UnmanagedType.LPWStr)> lpFileName As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> lpExistingFileName As String,   ' LPCWSTR
    lpSecurityAttributes As IntPtr,   ' SECURITY_ATTRIBUTES* optional
    hTransaction As IntPtr   ' HANDLE
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' lpFileName : LPCWSTR
' lpExistingFileName : LPCWSTR
' lpSecurityAttributes : SECURITY_ATTRIBUTES* optional
' hTransaction : HANDLE
Declare PtrSafe Function CreateHardLinkTransactedW Lib "kernel32" ( _
    ByVal lpFileName As LongPtr, _
    ByVal lpExistingFileName As LongPtr, _
    ByVal lpSecurityAttributes As LongPtr, _
    ByVal hTransaction As LongPtr) As Long
' 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

CreateHardLinkTransactedW = ctypes.windll.kernel32.CreateHardLinkTransactedW
CreateHardLinkTransactedW.restype = wintypes.BOOL
CreateHardLinkTransactedW.argtypes = [
    wintypes.LPCWSTR,  # lpFileName : LPCWSTR
    wintypes.LPCWSTR,  # lpExistingFileName : LPCWSTR
    ctypes.c_void_p,  # lpSecurityAttributes : SECURITY_ATTRIBUTES* optional
    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')
CreateHardLinkTransactedW = Fiddle::Function.new(
  lib['CreateHardLinkTransactedW'],
  [
    Fiddle::TYPE_VOIDP,  # lpFileName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # lpExistingFileName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # lpSecurityAttributes : SECURITY_ATTRIBUTES* optional
    Fiddle::TYPE_VOIDP,  # hTransaction : HANDLE
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "kernel32")]
extern "system" {
    fn CreateHardLinkTransactedW(
        lpFileName: *const u16,  // LPCWSTR
        lpExistingFileName: *const u16,  // LPCWSTR
        lpSecurityAttributes: *mut SECURITY_ATTRIBUTES,  // SECURITY_ATTRIBUTES* optional
        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.Unicode, SetLastError = true)]
public static extern bool CreateHardLinkTransactedW([MarshalAs(UnmanagedType.LPWStr)] string lpFileName, [MarshalAs(UnmanagedType.LPWStr)] string lpExistingFileName, IntPtr lpSecurityAttributes, IntPtr hTransaction);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_CreateHardLinkTransactedW' -Namespace Win32 -PassThru
# $api::CreateHardLinkTransactedW(lpFileName, lpExistingFileName, lpSecurityAttributes, hTransaction)

#uselib "KERNEL32.dll"
#func global CreateHardLinkTransactedW "CreateHardLinkTransactedW" wptr, wptr, wptr, wptr
; CreateHardLinkTransactedW lpFileName, lpExistingFileName, varptr(lpSecurityAttributes), hTransaction   ; 戻り値は stat
; lpFileName : LPCWSTR -> "wptr"
; lpExistingFileName : LPCWSTR -> "wptr"
; lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> "wptr"
; hTransaction : HANDLE -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global CreateHardLinkTransactedW "CreateHardLinkTransactedW" wstr, wstr, var, sptr
; res = CreateHardLinkTransactedW(lpFileName, lpExistingFileName, lpSecurityAttributes, hTransaction)
; lpFileName : LPCWSTR -> "wstr"
; lpExistingFileName : LPCWSTR -> "wstr"
; lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> "var"
; hTransaction : HANDLE -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global CreateHardLinkTransactedW "CreateHardLinkTransactedW" wstr, wstr, sptr, sptr
; res = CreateHardLinkTransactedW(lpFileName, lpExistingFileName, varptr(lpSecurityAttributes), hTransaction)
; lpFileName : LPCWSTR -> "wstr"
; lpExistingFileName : LPCWSTR -> "wstr"
; lpSecurityAttributes : SECURITY_ATTRIBUTES* optional -> "sptr"
; hTransaction : HANDLE -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。