ホーム › Storage.FileSystem › FindFirstFileNameW

FindFirstFileNameW

関数

ファイルに対する最初のハードリンク名を検索する。

DLLKERNEL32.dll呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

// KERNEL32.dll
#include <windows.h>

HANDLE FindFirstFileNameW(
    LPCWSTR lpFileName,
    DWORD dwFlags,
    DWORD* StringLength,
    LPWSTR LinkName
);

パラメーター

名前	型	方向	説明
lpFileName	LPCWSTR	in	ファイルの名前。ヒント Windows 10 バージョン 1607 以降では、"\\?\" を前に付けずに MAX_PATH の制限を解除することを選択できます。詳細については、ファイル、パス、および名前空間の名前付けの「最大パス長の制限」セクションを参照してください。
dwFlags	DWORD	in	予約済み。ゼロ (0) を指定します。
StringLength	DWORD*	inout	LinkName パラメーターが指すバッファーのサイズ (文字数)。この呼び出しが失敗し、 GetLastError 関数から返されるエラーが ERROR_MORE_DATA (234) の場合、このパラメーターによって返される値は、すべてのデータを格納するために LinkName が指すバッファーが必要とするサイズです。
LinkName	LPWSTR	out	lpFileName に対して最初に見つかったリンク名を格納するバッファーへのポインター。

戻り値の型: HANDLE

公式ドキュメント

指定したファイルに対するすべてのハードリンクの列挙を作成します。FindFirstFileNameW 関数は、列挙へのハンドルを返します。このハンドルは、後続の FindNextFileNameW 関数の呼び出しで使用できます。

戻り値

関数が成功した場合、戻り値は検索ハンドルであり、 FindNextFileNameW 関数で使用するか、 FindClose 関数で閉じることができます。

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

解説(Remarks)

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

テクノロジ	サポート
Server Message Block (SMB) 3.0 プロトコル	はい
SMB 3.0 トランスペアレントフェールオーバー (TFO)	いいえ
スケールアウトファイル共有 (SO) を使用した SMB 3.0	いいえ
クラスター共有ボリュームファイルシステム (CsvFS)	はい
復元性のあるファイルシステム (ReFS)	はい

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

各言語での呼び出し定義

// KERNEL32.dll
#include <windows.h>

HANDLE FindFirstFileNameW(
    LPCWSTR lpFileName,
    DWORD dwFlags,
    DWORD* StringLength,
    LPWSTR LinkName
);

[DllImport("KERNEL32.dll", SetLastError = true, ExactSpelling = true)]
static extern IntPtr FindFirstFileNameW(
    [MarshalAs(UnmanagedType.LPWStr)] string lpFileName,   // LPCWSTR
    uint dwFlags,   // DWORD
    ref uint StringLength,   // DWORD* in/out
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder LinkName   // LPWSTR out
);

<DllImport("KERNEL32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function FindFirstFileNameW(
    <MarshalAs(UnmanagedType.LPWStr)> lpFileName As String,   ' LPCWSTR
    dwFlags As UInteger,   ' DWORD
    ByRef StringLength As UInteger,   ' DWORD* in/out
    <MarshalAs(UnmanagedType.LPWStr)> LinkName As System.Text.StringBuilder   ' LPWSTR out
) As IntPtr
End Function

' lpFileName : LPCWSTR
' dwFlags : DWORD
' StringLength : DWORD* in/out
' LinkName : LPWSTR out
Declare PtrSafe Function FindFirstFileNameW Lib "kernel32" ( _
    ByVal lpFileName As LongPtr, _
    ByVal dwFlags As Long, _
    ByRef StringLength As Long, _
    ByVal LinkName As LongPtr) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

FindFirstFileNameW = ctypes.windll.kernel32.FindFirstFileNameW
FindFirstFileNameW.restype = ctypes.c_void_p
FindFirstFileNameW.argtypes = [
    wintypes.LPCWSTR,  # lpFileName : LPCWSTR
    wintypes.DWORD,  # dwFlags : DWORD
    ctypes.POINTER(wintypes.DWORD),  # StringLength : DWORD* in/out
    wintypes.LPWSTR,  # LinkName : LPWSTR out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
FindFirstFileNameW = Fiddle::Function.new(
  lib['FindFirstFileNameW'],
  [
    Fiddle::TYPE_VOIDP,  # lpFileName : LPCWSTR
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_VOIDP,  # StringLength : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # LinkName : LPWSTR out
  ],
  Fiddle::TYPE_VOIDP)

#[link(name = "kernel32")]
extern "system" {
    fn FindFirstFileNameW(
        lpFileName: *const u16,  // LPCWSTR
        dwFlags: u32,  // DWORD
        StringLength: *mut u32,  // DWORD* in/out
        LinkName: *mut u16  // LPWSTR out
    ) -> *mut core::ffi::c_void;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("KERNEL32.dll", SetLastError = true)]
public static extern IntPtr FindFirstFileNameW([MarshalAs(UnmanagedType.LPWStr)] string lpFileName, uint dwFlags, ref uint StringLength, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder LinkName);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_FindFirstFileNameW' -Namespace Win32 -PassThru
# $api::FindFirstFileNameW(lpFileName, dwFlags, StringLength, LinkName)

#uselib "KERNEL32.dll"
#func global FindFirstFileNameW "FindFirstFileNameW" sptr, sptr, sptr, sptr
; FindFirstFileNameW lpFileName, dwFlags, varptr(StringLength), varptr(LinkName)   ; 戻り値は stat
; lpFileName : LPCWSTR -> "sptr"
; dwFlags : DWORD -> "sptr"
; StringLength : DWORD* in/out -> "sptr"
; LinkName : LPWSTR out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global FindFirstFileNameW "FindFirstFileNameW" wstr, int, var, var
; res = FindFirstFileNameW(lpFileName, dwFlags, StringLength, LinkName)
; lpFileName : LPCWSTR -> "wstr"
; dwFlags : DWORD -> "int"
; StringLength : DWORD* in/out -> "var"
; LinkName : LPWSTR out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global FindFirstFileNameW "FindFirstFileNameW" wstr, int, sptr, sptr
; res = FindFirstFileNameW(lpFileName, dwFlags, varptr(StringLength), varptr(LinkName))
; lpFileName : LPCWSTR -> "wstr"
; dwFlags : DWORD -> "int"
; StringLength : DWORD* in/out -> "sptr"
; LinkName : LPWSTR out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。