FindFirstFileExW 関数 (fileapi.h)
指定したファイルまたはサブディレクトリに一致する名前と属性を持つファイルまたはサブディレクトリをディレクトリで検索します。
この関数の最も基本的なバージョンについては、「 FindFirstFile」を参照してください。
この操作をトランザクション操作として実行するには、 FindFirstFileTransacted 関数を 使用します。
構文
HANDLE FindFirstFileExW(
[in] LPCWSTR 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,000 文字のワイド文字に拡張するには、Unicode バージョンの関数 (FindFirstFileExW) を呼び出し、パスの先頭に "\\?\" を付加します。 詳細については、「ファイルの 名前付け」を参照してください。
[in] fInfoLevelId
返されるデータの情報レベル。
このパラメーターは、 FINDEX_INFO_LEVELS 列挙値の 1 つです。
[out] lpFindFileData
ファイル データを受信するバッファーへのポインター。
ポインター型は、 fInfoLevelId パラメーターで指定された情報のレベルによって決まります。
[in] fSearchOp
ワイルドカード一致とは異なる、実行するフィルター処理の種類。
このパラメーターは、 FINDEX_SEARCH_OPS 列挙値の 1 つです。
lpSearchFilter
指定した fSearchOp に構造化された検索情報が必要な場合は、検索条件へのポインター。
現時点では、サポートされている fSearchOp 値のいずれも拡張検索情報を必要としません。 したがって、このポインターは NULL である必要があります。
[in] dwAdditionalFlags
検索を制御する追加のフラグを指定します。
戻り値
関数が成功した場合、戻り値は FindNextFile または FindClose の後続の呼び出しで使用される検索ハンドルであり、 lpFindFileData パラメーターには最初に見つかったファイルまたはディレクトリに関する情報が含まれます。
関数が失敗するか、 lpFileName パラメーターの検索文字列からファイルを検索できない場合、戻り値は INVALID_HANDLE_VALUE され、 lpFindFileData の内容は不確定になります。 拡張エラー情報を取得するには、 GetLastError 関数を呼び出します。
Remarks
FindFirstFileEx 関数は、検索ハンドルを開き、指定したパターンに一致する名前でファイル システムが最初に見つけたファイルに関する情報を返します。 これは、同じファイル名の文字列パターンを指定した場合に、ディレクトリ一覧アプリケーション (dir コマンドなど) に表示される最初のファイルまたはディレクトリである場合とそうでない場合があります。 これは、 FindFirstFileEx が検索結果の並べ替えを行わないためです。 詳細については、「 FindNextFile」を参照してください。
次の一覧は、その他の検索特性を示しています。
- 検索は、日付やファイルの種類などの属性ではなく、ファイルの名前に対して厳密に実行されます。
- 検索には、長いファイル名と短いファイル名が含まれます。
- 末尾の円記号を使用して検索を開こうとすると、常に失敗します。
- lpFileName パラメーターに無効な文字列、NULL、または空の文字列を渡すことは、この関数の有効な使用ではありません。 この場合の結果は未定義です。
検索ハンドルが確立されたら、 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 を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | fileapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |