次の方法で共有

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) を呼び出し、パスの先頭に "\\?\" を付加します。 詳細については、「ファイルの名前付け」を参照してください。

ヒント Windows 10 バージョン 1607 以降では、この関数の Unicode バージョン (FindFirstFileExW) に対して、事前に "\\?\" を指定せずに 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

関連項目

FINDEX_INFO_LEVELS

FINDEX_SEARCH_OPS

ファイル管理機能の

FindClose

FindFirstFile の

FindFirstFileTransacted の

FindNextFile の

GetFileAttributes

ファイル の名前付けの

シンボリック リンク の

Windows ヘッダー の使用の

WIN32_FIND_DATA