FindFirstFileTransactedW 函式 (winbase.h)
[Microsoft 強烈建議開發人員利用替代方法來達成應用程式的需求。 許多針對 TxF 開發的案例，都可以透過更簡單且更容易取得的技術來達成。 此外，未來版本的 Microsoft Windows 可能無法使用 TxF。 如需詳細資訊，以及 TxF 的替代方案，請參閱 使用交易式 NTFS 的替代方案。]
使用符合特定名稱做為交易作業的名稱，搜尋目錄中的檔案或子目錄。
此函式是 FindFirstFileEx 函 式的交易形式。
如需此函式的最基本版本，請參閱 FindFirstFile。
語法
HANDLE FindFirstFileTransactedW(
[in] LPCWSTR lpFileName,
[in] FINDEX_INFO_LEVELS fInfoLevelId,
[out] LPVOID lpFindFileData,
[in] FINDEX_SEARCH_OPS fSearchOp,
LPVOID lpSearchFilter,
[in] DWORD dwAdditionalFlags,
[in] HANDLE hTransaction
);
參數
[in] lpFileName
目錄或路徑，以及檔案名。 檔案名可以包含萬用字元，例如星號 (*) 或問號 (？) 。
此參數不應該是 Null、不正確字串 (例如空字串或遺漏終止 Null 字元) 的字串，或結尾為尾端反斜線 (\) 。
如果字串以萬用字元、句號 (.) 或目錄名稱結尾，則使用者必須能夠存取路徑上的根目錄和所有子目錄。
檔案必須位於本機電腦上;否則，函式會失敗，並將最後一個錯誤碼設定為 ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE。
根據預設，名稱限制為MAX_PATH個字元。 若要將此限制延伸至 32，767 寬字元，請在路徑前面加上 「\\？\」。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。
提示
從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 「\\？\」。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的一節。
[in] fInfoLevelId
傳回資料的資訊層級。
此參數是其中一個 FINDEX_INFO_LEVELS 列舉值。
[out] lpFindFileData
WIN32_FIND_DATA結構的指標，可接收所找到檔案或子目錄的相關資訊。
[in] fSearchOp
要執行的篩選類型，與萬用字元比對不同。
此參數是其中一個 FINDEX_SEARCH_OPS 列舉值。
lpSearchFilter
如果指定的 fSearchOp 需要結構化搜尋資訊，則為搜尋準則的指標。
目前，不支援的 fSearchOp 值都不需要擴充搜尋資訊。 因此，此指標必須是 Null。
[in] dwAdditionalFlags
指定控制搜尋的其他旗標。
| 值 | 意義 |
|---|---|
|
搜尋會區分大小寫。 |
[in] hTransaction
交易的控制碼。 CreateTransaction函式會傳回此控制碼。
傳回值
如果函式成功，傳回值是搜尋控制碼，用於 後續呼叫 FindNextFile 或 FindClose，而 lpFindFileData 參數包含第一個找到之檔案或目錄的相關資訊。
如果函式失敗或無法從 lpFileName 參數中的搜尋字串找到檔案，則會 INVALID_HANDLE_VALUE 傳回值，而且 lpFindFileData 的內容不定。 若要取得擴充的錯誤資訊，請呼叫 GetLastError 函 式。
備註
FindFirstFileTransacted函式會開啟搜尋控制碼，並傳回檔案系統找到之名稱符合指定模式之第一個檔案的相關資訊。 當指定相同的檔案名字串模式時，這可能不是出現在目錄清單應用程式中的第一個檔案或目錄 (，例如 dir 命令) 。 這是因為 FindFirstFileTransacted 不會排序搜尋結果。 如需詳細資訊，請參閱 FindNextFile。
下列清單會識別一些其他搜尋特性：
- 搜尋會嚴格執行于檔案名上，而不是在日期或檔案類型等任何屬性上執行。
- 搜尋包含長和短檔案名。
- 嘗試開啟具有尾端反斜線的搜尋一律會失敗。
- 為lpFileName參數傳遞不正確字串、Null或空字串，不是有效使用此函式。 在此情況下的結果是未定義的。
建立搜尋控制碼之後，請在 FindNextFile 函式中使用該控制碼來搜尋符合相同模式且執行相同篩選的其他檔案。 不需要搜尋控制碼時，應該使用 FindClose 函式加以關閉。
如先前所述，您無法在FindFirstFileFileTransacted的lpFileName輸入字串中使用尾端反斜線 (\) ，因此搜尋根目錄的方式可能並不明顯。 如果您想要查看檔案或取得根目錄的屬性，則會套用下列選項：
- 若要檢查根目錄中的檔案，您可以使用 「C：\*」，並使用 FindNextFile逐步執行目錄。
- 若要取得根目錄的屬性，請使用 GetFileAttributes 函式。
在網路共用上，您可以使用下列格式的 lpFileName ：「\\server\service*」。 不過，您無法使用指向共用本身的 lpFileName ;例如，「\\server\service」 無效。
若要檢查不是根目錄的目錄，請使用該目錄的路徑，而不使用尾端反斜線。 例如，「C：\Windows」 的引數會傳回目錄 「C：\Windows」 的相關資訊，而不是 「C：\Windows」 中的目錄或檔案。 若要檢查 「C：\Windows」 中的檔案和目錄，請使用 「C：\Windows\*」 的 lpFileName 。
請注意，有些其他執行緒或進程可以在查詢結果與處理資訊的時間之間，建立或刪除具有此名稱的檔案。 如果這是應用程式的潛在考慮，其中一個可能的解決方案是使用 CreateFile 函式搭配 CREATE_NEW (，如果檔案存在) 失敗，或 OPEN_EXISTING (檔案不存在) 則失敗。
如果您要撰寫 32 位應用程式來列出目錄中的所有檔案，而且應用程式可能會在 64 位電腦上執行，您應該先呼叫 Wow64DisableWow64FsRedirection ，再呼叫 FindFirstFileTransacted 並呼叫 Wow64RevertWow64FsRedirection ，再呼叫 FindNextFile。 如需詳細資訊，請參閱 檔案系統重新導向器。
如果路徑指向符號連結， 則WIN32_FIND_DATA 緩衝區包含符號連結的相關資訊，而不是目標。
在Windows 8和Windows Server 2012中，下列技術支援此函式。
| 技術 | 支援 |
|---|---|
| 伺服器訊息區 (SMB) 3.0 通訊協定 | No |
| SMB 3.0 透明容錯移轉 (TFO) | No |
| 具有向外延展檔案共用的 SMB 3.0 (SO) | No |
| 叢集共用磁片區檔案系統 (CsvFS) | No |
| 彈性檔案系統 (ReFS) | No |
SMB 3.0 不支援 TxF。
注意
winbase.h 標頭會根據 UNICODE 預處理器常數的定義，將 FindFirstFileTransacted 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 最低支援的用戶端 | Windows Vista [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | winbase.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |