FindFirstFileExA 関数 (fileapi.h)

[アーティクル]
06/02/2023

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

この関数の最も基本的なバージョンについては、「 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 関数を呼び出します。

Remarks

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

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

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

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

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

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

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

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

メモ文字列 "\\?\" をプリペンドしても、ルートディレクトリへのアクセスは許可されません。

ネットワーク共有では、 lpFileName を "\\server\service\*" の形式で使用できます。ただし、共有自体を指す 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 Transparent Failover (TFO)	はい
スケールアウトファイル共有を含む SMB 3.0 (SO)	はい
クラスター共有ボリュームファイルシステム (CsvFS)	はい
Resilient File System (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 を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件


サポートされている最小のクライアント	Windows XP [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	fileapi.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

次の方法で共有

FindFirstFileExA 関数 (fileapi.h)

構文

パラメーター

戻り値

Remarks

例

要件

関連項目

フィードバック

その他のリソース