FindFirstFileW 函式 (fileapi.h)
使用通配符時，搜尋符合特定名稱的檔案或子目錄 (或部分名稱的目錄) 。
若要指定要在搜尋中使用的其他屬性，請使用 FindFirstFileEx 函式。
若要以交易作業的形式執行此作業，請使用 FindFirstFileTransacted 函式 。
語法
HANDLE FindFirstFileW(
[in] LPCWSTR lpFileName,
[out] LPWIN32_FIND_DATAW lpFindFileData
);
參數
[in] lpFileName
目錄或路徑，以及檔名。 檔名可以包含通配符，例如星號 (*) 或問號 (？) 。
此參數不應為 NULL、無效的字串 (例如空字串或遺漏終止 Null 字元的字串) ，或結尾為尾端反斜杠 (\) 。
如果字串以通配符、句號 (.) 或目錄名稱結尾，則用戶必須具有路徑上根目錄和所有子目錄的訪問許可權。
根據預設，名稱限製為MAX_PATH個字元。 若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。
提示
從版本 1607 Windows 10 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的一節。
[out] lpFindFileData
可接收所找到檔案或目錄相關信息 之WIN32_FIND_DATA 結構的指標。
傳回值
如果函式成功，則傳回值是搜尋句柄，用於後續呼叫 FindNextFile 或 FindClose， 而 lpFindFileData 參數包含找到的第一個檔案或目錄的相關信息。
如果函式失敗或無法從 lpFileName 參數中的搜尋字串找出檔案，傳回值 會INVALID_HANDLE_VALUE 且 lpFindFileData 的內容不確定。 若要取得擴充的錯誤資訊，請呼叫 GetLastError 函式。
如果函式失敗，因為找不到相符的檔案， GetLastError 函式會傳回 ERROR_FILE_NOT_FOUND。
備註
FindFirstFile 函式會開啟搜尋句柄，並傳回文件系統以符合指定模式的名稱尋找之第一個檔案的相關信息。 當指定相同的檔名字符串模式時，這可能不是出現在目錄清單應用程式中的第一個檔案或目錄 (，例如 dir 命令) 。 這是因為 FindFirstFile 不會排序搜尋結果。 如需詳細資訊，請參閱 FindNextFile。
下列清單會識別一些其他搜尋特性：
- 搜尋會嚴格地對檔名執行，而不是日期或檔類型等任何屬性， (其他選項，請參閱 FindFirstFileEx) 。
- 搜尋包含長檔名和簡短檔名。
- 嘗試以尾端反斜杠開啟搜尋一律會失敗。
- 傳遞 lpFileName 參數的無效字串、NULL 或空字串不是這個函式的有效用法。 在此情況下的結果未定義。
不再需要搜尋句柄時，請使用 FindClose 函式關閉它，而不是 CloseHandle。
如先前所述，您無法在 FindFirstFile 的 lpFileName 輸入字串中使用尾端反斜杠 (\) ，因此搜尋根目錄可能不明顯。 如果您要檢視檔案或取得根目錄的屬性，則會套用下列選項：
- 若要檢查根目錄中的檔案，您可以使用 “C：\*”，並使用 FindNextFile 逐步執行目錄。
- 若要取得根目錄的屬性，請使用 GetFileAttributes 函式 。
在網路共用上，您可以使用下列格式的 lpFileName ：“\\Server\Share\*”。 不過，您無法使用指向共用本身的 lpFileName ;例如，“\\Server\Share” 無效。
若要檢查不是根目錄的目錄，請使用該目錄的路徑，而不需尾端反斜杠。 例如，“C：\Windows” 的自變數會傳回目錄 “C：\Windows” 的相關信息，而不是 “C：\Windows” 中的目錄或檔案。 若要檢查 「C：\Windows」 中的檔案和目錄，請使用 “C：\Windows\*” 的 lpFileName 。
請注意，某些其他線程或進程可以在查詢結果和處理資訊的時間之間，建立或刪除具有此名稱的檔案。 如果這是應用程式的潛在考慮，其中一個可能的解決方案是使用 CreateFile 函式搭配 CREATE_NEW (，如果檔案存在) 或 OPEN_EXISTING (檔案不存在) ，就會失敗。
如果您要撰寫 32 位應用程式來列出目錄中的所有檔案，而且應用程式可以在 64 位電腦上執行，您應該先呼叫 Wow64DisableWow64FsRedirection 函式，再呼叫 FindFirstFile 並呼叫 Wow64RevertWow64FsRedirection ，再呼叫 FindNextFile。 如需詳細資訊，請參閱 文件系統重新導向器。
如果路徑指向符號連結， 則WIN32_FIND_DATA 緩衝區包含符號連結的相關信息，而不是目標。
在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。
| 技術 | 支援 |
|---|---|
| 伺服器消息塊 (SMB) 3.0 通訊協定 | Yes |
| SMB 3.0 透明故障轉移 (TFO) | Yes |
| 具有向外延展檔案共用的SMB 3.0 (SO) | Yes |
| 叢集共用磁碟區文件系統 (CsvFS) | Yes |
| 彈性檔案系統 (ReFS) | 是 |
範例
下列 C++ 範例示範 使用 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 = FindFirstFile(argv[1], &FindFileData);
if (hFind == INVALID_HANDLE_VALUE)
{
printf ("FindFirstFile failed (%d)\n", GetLastError());
return;
}
else
{
_tprintf (TEXT("The first file found is %s\n"),
FindFileData.cFileName);
FindClose(hFind);
}
}
如需其他範例，請參閱 列出目錄中的檔案。
注意
fileapi.h 標頭會將 FindFirstFile 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | fileapi.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |