FindFirstFileExA 関数 (fileapi.h)

[アーティクル]
11/20/2024

指定されたファイルまたはサブディレクトリに一致する名前と属性を持つディレクトリを検索します。

この関数の最も基本的なバージョンについては、「FindFirstFileを参照してください。

この操作をトランザクション操作として実行するには、FindFirstFileTransacted 関数を使用します。

構文

HANDLE FindFirstFileExA(
  [in]  LPCSTR             lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags
);

パラメーター

[in] lpFileName

ディレクトリまたはパス、およびファイル名。ファイル名には、アスタリスク (*) や疑問符 (?) などのワイルドカード文字を含めることができます。

このパラメーターは、NULL、無効な文字列 (空の文字列、終端の null 文字がない文字列など)、末尾の円記号 (\) で終わるすることはできません。

文字列がワイルドカード、ピリオド、またはディレクトリ名で終わる場合、ユーザーはルートとパス上のすべてのサブディレクトリにアクセスできる必要があります。

既定では、名前はMAX_PATH文字に制限されています。この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付けます。詳細については、「ファイル、パス、および名前空間の名前付けする」を参照してください。

先端

Windows 10 バージョン 1607 以降では、事前に "\\?\" なしでMAX_PATHの制限を削除することをオプトインできます。詳細については、「名前付けファイル、パス、および名前空間の」の「パスの最大長制限」セクションを参照してください。

[in] fInfoLevelId

返されるデータの情報レベル。

このパラメーターは、FINDEX_INFO_LEVELS 列挙値の 1 つです。

[out] lpFindFileData

ファイルデータを受け取るバッファーへのポインター。

ポインター型は、fInfoLevelId パラメーターで指定された情報のレベルによって決まります。

[in] fSearchOp

ワイルドカード照合とは異なる、実行するフィルター処理の種類。

このパラメーターは、FINDEX_SEARCH_OPS 列挙値の 1 つです。

lpSearchFilter

指定した fSearchOp に構造化された検索情報が必要な場合は、検索条件へのポインター。

現時点では、サポートされている fSearchOp 値拡張検索情報は必要ありません。したがって、このポインターは NULLする必要があります。

[in] dwAdditionalFlags

検索を制御する追加のフラグを指定します。

価値	意味
FIND_FIRST_EX_CASE_SENSITIVE 1	検索では大文字と小文字が区別されます。
FIND_FIRST_EX_LARGE_FETCH 2	ディレクトリクエリに大きなバッファーを使用し、検索操作のパフォーマンスを向上させることができます。 Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値は、Windows Server 2008 R2 および Windows 7 までサポートされていません。
FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY 4	結果をディスク上の物理的なファイルに制限します。このフラグは、ファイル仮想化フィルターが存在する場合にのみ関連します。

戻り値

関数が成功した場合、戻り値は、FindNextFile または FindCloseをする後続の呼び出しで使用される検索ハンドルであり、lpFindFileData パラメーターには、最初に見つかったファイルまたはディレクトリに関する情報が含まれます。

lpFileName パラメーター内の検索文字列からファイルを検索できないか、関数が失敗した場合、戻り値は INVALID_HANDLE_VALUE され、lpFindFileData の内容は不確定になります。拡張エラー情報を取得するには、GetLastError 関数を呼び出します。

備考

FindFirstFileEx 関数は、検索ハンドルを開き、指定したパターンに一致する名前でファイルシステムが最初に見つけたファイルに関する情報を返します。これは、同じファイル名の文字列パターンを指定した場合に、ディレクトリ一覧アプリケーション (dir コマンドなど) に表示される最初のファイルまたはディレクトリである場合とそうでない場合があります。これは、FindFirstFileEx 検索結果の並べ替えが行われません。詳細については、「FindNextFileを参照してください。

次の一覧は、その他の検索特性を示しています。

検索は、日付やファイルの種類などの属性ではなく、ファイルの名前に厳密に実行されます。
検索には、長いファイル名と短いファイル名が含まれます。
末尾の円記号を使用して検索を開こうとすると、常に失敗します。
lpFileName パラメーターに無効な文字列、NULL、または空の文字列を渡すことは、この関数の有効な使用ではありません。この場合の結果は未定義です。

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

基になるファイルシステムが、ディレクトリフィルター処理以外の指定された種類のフィルター処理をサポートしていない場合、FindFirstFileEx エラー ERROR_NOT_SUPPORTEDで失敗します。アプリケーションでは、FileExSearchNameMatch FINDEX_SEARCH_OPS 型を使用し、独自のフィルター処理を実行する必要があります。

検索ハンドルが確立されたら、FindNextFile 関数でそれを使用して、同じパターンと同じフィルター処理が実行されている他のファイルを検索します。検索ハンドルが不要な場合は、FindClose 関数を使用して閉じる必要があります。

前述のように、FindFirstFileExの lpFileName 入力文字列で末尾の円記号 (\) を使用することはできません。そのため、ルートディレクトリを検索する方法が明確でない可能性があります。ファイルを表示したり、ルートディレクトリの属性を取得したりする場合は、次のオプションが適用されます。

ルートディレクトリ内のファイルを調べるには、"C:\*" を使用し、FindNextFileを使用してディレクトリをステップ実行できます。
ルートディレクトリの属性を取得するには、GetFileAttributes 関数を使用します。

メモ文字列 "\\?\" はルートディレクトリへのアクセスを許可しません。

ネットワーク共有では、"\\server\service\*" の形式で lpFileName を使用できます。ただし、共有自体を指す lpFileName を使用することはできません。たとえば、"\\server\service" は無効です。

ルートディレクトリではないディレクトリを調べるには、末尾の円記号を付けずに、そのディレクトリへのパスを使用します。たとえば、"C:\Windows" の引数は、"C:\Windows" のディレクトリまたはファイルではなく、ディレクトリ "C:\Windows" に関する情報を返します。 "C:\Windows" のファイルとディレクトリを調べるには、"C:\Windows\*" の lpFileName を使用します。

次の呼び出し:

FindFirstFileEx( lpFileName, 
                 FindExInfoStandard, 
                 lpFindData, 
                 FindExSearchNameMatch, 
                 NULL, 
                 0 );

次の呼び出しと同じです。

FindFirstFile( lpFileName, lpFindData );

他のスレッドまたはプロセスでは、結果のクエリを実行してから情報に対して実行するまでの間に、この名前のファイルが作成または削除される可能性があることに注意してください。これがアプリケーションの潜在的な懸念事項である場合、考えられる解決策の 1 つは、CreateFile 関数を CREATE_NEW (ファイルが存在する場合は失敗します) または OPEN_EXISTING (ファイルが存在しない場合は失敗します) と共に使用することです。

ディレクトリ内のすべてのファイルを一覧表示する 32 ビットアプリケーションを作成していて、アプリケーションが 64 ビットコンピューターで実行される可能性がある場合は、 FindFirstFileEx を呼び出す前に、Wow64DisableWow64FsRedirection 呼び出し、FindNextFileへの最後の呼び出しの後に Wow64RevertWow64FsRedirection を呼び出す必要があります。詳細については、「ファイルシステムリダイレクター」を参照してください。

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

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

テクノロジー	サポート
サーバーメッセージブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 透過的フェールオーバー (TFO)	はい
SMB 3.0 とスケールアウトファイル共有 (SO)	はい
クラスター共有ボリュームファイルシステム (CsvFS)	はい
回復性のあるファイルシステム (ReFS)	はい

例

次のコードは、FindFirstFileExの最小限の使用を示しています。このプログラムは、FindFirstFile トピックの例と同じです。

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

void _tmain(int argc, TCHAR *argv[])
{
   WIN32_FIND_DATA FindFileData;
   HANDLE hFind;

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
      return;
   }

   _tprintf (TEXT("Target file is %s\n"), argv[1]);
   hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData,
             FindExSearchNameMatch, NULL, 0);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFileEx failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

手記

fileapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして FindFirstFileEx を定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリ \|UWP アプリ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリ \|UWP アプリ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	fileapi.h (Windows.h を含む)
ライブラリ	Kernel32.lib
DLL	Kernel32.dll

次の方法で共有

FindFirstFileExA 関数 (fileapi.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース