ホーム › Storage.FileSystem › FindNextFileA

FindNextFileA

関数

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

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

シグネチャ

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

BOOL FindNextFileA(
    HANDLE hFindFile,
    WIN32_FIND_DATAA* lpFindFileData
);

パラメーター

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

戻り値の型: BOOL

公式ドキュメント

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

戻り値

関数が成功した場合、戻り値は 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)	はい

トランザクション操作

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

例

例については、 Listing the Files in a Directory を参照してください。

メモ

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

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

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

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

' hFindFile : HANDLE
' lpFindFileData : WIN32_FIND_DATAA* out
Declare PtrSafe Function FindNextFileA Lib "kernel32" ( _
    ByVal hFindFile As LongPtr, _
    ByVal lpFindFileData As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
FindNextFileA = Fiddle::Function.new(
  lib['FindNextFileA'],
  [
    Fiddle::TYPE_VOIDP,  # hFindFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpFindFileData : WIN32_FIND_DATAA* out
  ],
  Fiddle::TYPE_INT)

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

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

出力引数:

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