ホーム › Storage.FileSystem › FindNextFileW

FindNextFileW

関数

前回の検索条件で次のファイルを取得する。

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

シグネチャ

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

BOOL FindNextFileW(
    HANDLE hFindFile,
    WIN32_FIND_DATAW* lpFindFileData
);

パラメーター

名前	型	方向	説明
hFindFile	HANDLE	in	以前の FindFirstFile または FindFirstFileEx 関数の呼び出しによって返された検索ハンドルです。
lpFindFileData	WIN32_FIND_DATAW*	out	見つかったファイルまたはサブディレクトリに関する情報を受け取る WIN32_FIND_DATA 構造体へのポインターです。

戻り値の型: BOOL

公式ドキュメント

FindFirstFile、FindFirstFileEx、または FindFirstFileTransacted 関数への以前の呼び出しから、ファイル検索を続行します。(Unicode)

戻り値

関数が成功した場合、戻り値は 0 以外となり、lpFindFileData パラメーターには次に見つかったファイルまたはディレクトリに関する情報が格納されます。

関数が失敗した場合、戻り値は 0 となり、lpFindFileData の内容は不定です。拡張エラー情報を取得するには、 GetLastError 関数を呼び出してください。

一致するファイルがこれ以上見つからないことが原因で関数が失敗した場合、 GetLastError 関数は ERROR_NO_MORE_FILES を返します。

解説(Remarks)

この関数は、hFindFile パラメーターで渡された検索ハンドルの作成に使用されたものと同じ検索フィルターを使用します。詳細については、 FindFirstFile および FindFirstFileEx を参照してください。

検索がファイルを返す順序(アルファベット順など)は保証されておらず、ファイルシステムに依存します。データをソートする必要がある場合は、アプリケーションがすべての結果を取得した後に並べ替えを行う必要があります。

注意まれなケースや、負荷の高いシステムでは、NTFS ファイルシステム上のファイル属性情報がこの関数の呼び出し時点で最新でない場合があります。現在の NTFS ファイルシステムのファイル属性を確実に取得するには、 GetFileInformationByHandle 関数を呼び出してください。

この関数がファイル名を返す順序は、ファイルシステムの種類に依存します。NTFS ファイルシステムおよび CDFS ファイルシステムでは、通常、名前はアルファベット順で返されます。FAT ファイルシステムでは、通常、名前はファイルがディスクに書き込まれた順序で返されますが、これはアルファベット順である場合とそうでない場合があります。ただし、前述のとおり、これらの動作は保証されていません。

パスがシンボリックリンクを指している場合、 WIN32_FIND_DATA バッファーには、ターゲットではなくシンボリックリンクに関する情報が格納されます。

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

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

トランザクション操作

ファイル列挙ハンドルにバインドされたトランザクションがある場合、返されるファイルはトランザクション分離規則の対象となります。

例

例については、ディレクトリ内のファイルの一覧表示を参照してください。

メモ

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

出典・ライセンス: 上記「公式ドキュメント」の内容は 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 FindNextFileW(
    HANDLE hFindFile,
    WIN32_FIND_DATAW* lpFindFileData
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern bool FindNextFileW(
    IntPtr hFindFile,   // HANDLE
    IntPtr lpFindFileData   // WIN32_FIND_DATAW* out
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function FindNextFileW(
    hFindFile As IntPtr,   ' HANDLE
    lpFindFileData As IntPtr   ' WIN32_FIND_DATAW* out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hFindFile : HANDLE
' lpFindFileData : WIN32_FIND_DATAW* out
Declare PtrSafe Function FindNextFileW Lib "kernel32" ( _
    ByVal hFindFile As LongPtr, _
    ByVal lpFindFileData 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

FindNextFileW = ctypes.windll.kernel32.FindNextFileW
FindNextFileW.restype = wintypes.BOOL
FindNextFileW.argtypes = [
    wintypes.HANDLE,  # hFindFile : HANDLE
    ctypes.c_void_p,  # lpFindFileData : WIN32_FIND_DATAW* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
FindNextFileW = Fiddle::Function.new(
  lib['FindNextFileW'],
  [
    Fiddle::TYPE_VOIDP,  # hFindFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpFindFileData : WIN32_FIND_DATAW* out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "kernel32")]
extern "system" {
    fn FindNextFileW(
        hFindFile: *mut core::ffi::c_void,  // HANDLE
        lpFindFileData: *mut WIN32_FIND_DATAW  // WIN32_FIND_DATAW* out
    ) -> 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 FindNextFileW(IntPtr hFindFile, IntPtr lpFindFileData);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_FindNextFileW' -Namespace Win32 -PassThru
# $api::FindNextFileW(hFindFile, lpFindFileData)

#uselib "KERNEL32.dll"
#func global FindNextFileW "FindNextFileW" wptr, wptr
; FindNextFileW hFindFile, varptr(lpFindFileData)   ; 戻り値は stat
; hFindFile : HANDLE -> "wptr"
; lpFindFileData : WIN32_FIND_DATAW* out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global FindNextFileW "FindNextFileW" sptr, var
; res = FindNextFileW(hFindFile, lpFindFileData)
; hFindFile : HANDLE -> "sptr"
; lpFindFileData : WIN32_FIND_DATAW* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global FindNextFileW "FindNextFileW" sptr, sptr
; res = FindNextFileW(hFindFile, varptr(lpFindFileData))
; hFindFile : HANDLE -> "sptr"
; lpFindFileData : WIN32_FIND_DATAW* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。