ホーム › Storage.FileSystem › GetFullPathNameTransactedA

GetFullPathNameTransactedA

関数

トランザクション内でファイルの完全パス名を取得する(ANSI版)。

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

シグネチャ

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

DWORD GetFullPathNameTransactedA(
    LPCSTR lpFileName,
    DWORD nBufferLength,
    LPSTR lpBuffer,   // optional
    LPSTR* lpFilePart,   // optional
    HANDLE hTransaction
);

パラメーター

名前	型	方向	説明
lpFileName	LPCSTR	in	ファイルの名前。この文字列には、短い形式 (8.3 形式) または長い形式のファイル名を使用できます。この文字列は、共有名またはボリューム名にすることもできます。ファイルはローカルコンピューター上に存在する必要があります。そうでない場合、関数は失敗し、最終エラーコードに ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE が設定されます。
nBufferLength	DWORD	in	ドライブとパスを表す null 終端文字列を受け取るバッファーのサイズ。単位は TCHAR です。
lpBuffer	LPSTR	outoptional	ドライブとパスを表す null 終端文字列を受け取るバッファーへのポインター。
lpFilePart	LPSTR*	outoptional	パス内の最後のファイル名コンポーネントのアドレス (lpBuffer 内) を受け取るバッファーへのポインター。この情報を受け取る必要がない場合は NULL を指定します。 lpBuffer がファイルではなくディレクトリを指している場合、lpFilePart は 0 (ゼロ) を受け取ります。
hTransaction	HANDLE	in	トランザクションへのハンドル。このハンドルは CreateTransaction 関数によって返されます。

戻り値の型: DWORD

公式ドキュメント

指定したファイルのフルパスとファイル名を、トランザクション操作として取得します。(ANSI)

戻り値

関数が成功した場合、戻り値は lpBuffer にコピーされた文字列の長さ (終端の null 文字を含まない) で、単位は TCHAR です。

lpBuffer バッファーがパスを格納するには小さすぎる場合、戻り値はパスと終端の null 文字を保持するために必要なバッファーのサイズ (単位は TCHAR) になります。

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

解説(Remarks)

GetFullPathNameTransacted は、現在のドライブとディレクトリの名前を指定したファイル名と結合して、指定したファイルのフルパスとファイル名を求めます。また、フルパスおよびファイル名内のファイル名部分のアドレスも算出します。この関数は、結果として得られるパスとファイル名が有効かどうか、または関連付けられたボリューム上の既存のファイルを指しているかどうかを検証しません。

共有名およびボリューム名は lpFileName の有効な入力です。たとえば、test-2 がリモートコンピューターで、U: がネットワークマップされたドライブである場合、返されるパスとファイル名は次のとおりです。

"\\test-2\q$\lh" を指定した場合、返されるパスは "\\test-2\q$\lh" です
"\\?\UNC\test-2\q$\lh" を指定した場合、返されるパスは "\\?\UNC\test-2\q$\lh" です
"U:" を指定した場合、返されるパスは "U:\" です

GetFullPathNameTransacted は、指定したファイル名 lpFileName を変換しません。指定したファイル名が存在する場合は、 GetLongPathNameTransacted、 GetLongPathName、または GetShortPathName を使用して、それぞれ長い形式または短い形式のパス名に変換できます。

戻り値が nBufferLength に指定した値より大きい場合、パスを保持するのに十分な大きさのバッファーを用意して、再度この関数を呼び出すことができます。このケースの例、および動的割り当てのために長さ 0 のバッファーを使用する例については、サンプルコードのセクションを参照してください。

注意このケースでの戻り値は終端の null 文字を含む長さですが、成功時の戻り値はそのカウントに終端の null 文字を含みません。

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

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

DWORD GetFullPathNameTransactedA(
    LPCSTR lpFileName,
    DWORD nBufferLength,
    LPSTR lpBuffer,   // optional
    LPSTR* lpFilePart,   // optional
    HANDLE hTransaction
);

[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern uint GetFullPathNameTransactedA(
    [MarshalAs(UnmanagedType.LPStr)] string lpFileName,   // LPCSTR
    uint nBufferLength,   // DWORD
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder lpBuffer,   // LPSTR optional, out
    IntPtr lpFilePart,   // LPSTR* optional, out
    IntPtr hTransaction   // HANDLE
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function GetFullPathNameTransactedA(
    <MarshalAs(UnmanagedType.LPStr)> lpFileName As String,   ' LPCSTR
    nBufferLength As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPStr)> lpBuffer As System.Text.StringBuilder,   ' LPSTR optional, out
    lpFilePart As IntPtr,   ' LPSTR* optional, out
    hTransaction As IntPtr   ' HANDLE
) As UInteger
End Function

' lpFileName : LPCSTR
' nBufferLength : DWORD
' lpBuffer : LPSTR optional, out
' lpFilePart : LPSTR* optional, out
' hTransaction : HANDLE
Declare PtrSafe Function GetFullPathNameTransactedA Lib "kernel32" ( _
    ByVal lpFileName As String, _
    ByVal nBufferLength As Long, _
    ByVal lpBuffer As String, _
    ByVal lpFilePart As LongPtr, _
    ByVal hTransaction As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetFullPathNameTransactedA = ctypes.windll.kernel32.GetFullPathNameTransactedA
GetFullPathNameTransactedA.restype = wintypes.DWORD
GetFullPathNameTransactedA.argtypes = [
    wintypes.LPCSTR,  # lpFileName : LPCSTR
    wintypes.DWORD,  # nBufferLength : DWORD
    wintypes.LPSTR,  # lpBuffer : LPSTR optional, out
    ctypes.c_void_p,  # lpFilePart : LPSTR* optional, out
    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')
GetFullPathNameTransactedA = Fiddle::Function.new(
  lib['GetFullPathNameTransactedA'],
  [
    Fiddle::TYPE_VOIDP,  # lpFileName : LPCSTR
    -Fiddle::TYPE_INT,  # nBufferLength : DWORD
    Fiddle::TYPE_VOIDP,  # lpBuffer : LPSTR optional, out
    Fiddle::TYPE_VOIDP,  # lpFilePart : LPSTR* optional, out
    Fiddle::TYPE_VOIDP,  # hTransaction : HANDLE
  ],
  -Fiddle::TYPE_INT)

#[link(name = "kernel32")]
extern "system" {
    fn GetFullPathNameTransactedA(
        lpFileName: *const u8,  // LPCSTR
        nBufferLength: u32,  // DWORD
        lpBuffer: *mut u8,  // LPSTR optional, out
        lpFilePart: *mut *mut u8,  // LPSTR* optional, out
        hTransaction: *mut core::ffi::c_void  // HANDLE
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern uint GetFullPathNameTransactedA([MarshalAs(UnmanagedType.LPStr)] string lpFileName, uint nBufferLength, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder lpBuffer, IntPtr lpFilePart, IntPtr hTransaction);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_GetFullPathNameTransactedA' -Namespace Win32 -PassThru
# $api::GetFullPathNameTransactedA(lpFileName, nBufferLength, lpBuffer, lpFilePart, hTransaction)

#uselib "KERNEL32.dll"
#func global GetFullPathNameTransactedA "GetFullPathNameTransactedA" sptr, sptr, sptr, sptr, sptr
; GetFullPathNameTransactedA lpFileName, nBufferLength, varptr(lpBuffer), varptr(lpFilePart), hTransaction   ; 戻り値は stat
; lpFileName : LPCSTR -> "sptr"
; nBufferLength : DWORD -> "sptr"
; lpBuffer : LPSTR optional, out -> "sptr"
; lpFilePart : LPSTR* optional, out -> "sptr"
; hTransaction : HANDLE -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global GetFullPathNameTransactedA "GetFullPathNameTransactedA" str, int, var, var, sptr
; res = GetFullPathNameTransactedA(lpFileName, nBufferLength, lpBuffer, lpFilePart, hTransaction)
; lpFileName : LPCSTR -> "str"
; nBufferLength : DWORD -> "int"
; lpBuffer : LPSTR optional, out -> "var"
; lpFilePart : LPSTR* optional, out -> "var"
; hTransaction : HANDLE -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global GetFullPathNameTransactedA "GetFullPathNameTransactedA" str, int, sptr, sptr, sptr
; res = GetFullPathNameTransactedA(lpFileName, nBufferLength, varptr(lpBuffer), varptr(lpFilePart), hTransaction)
; lpFileName : LPCSTR -> "str"
; nBufferLength : DWORD -> "int"
; lpBuffer : LPSTR optional, out -> "sptr"
; lpFilePart : LPSTR* optional, out -> "sptr"
; hTransaction : HANDLE -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。