FindFirstFileTransactedA 函式 (winbase.h)

  • 發行項

[Microsoft 強烈建議開發人員利用替代方法來達成應用程式的需求。 許多針對 TxF 開發的案例，都可以透過更簡單且更容易取得的技術來達成。 此外，未來版本的 Microsoft Windows 可能無法使用 TxF。 如需詳細資訊，以及 TxF 的替代方案，請參閱 使用交易式 NTFS 的替代方案。]

使用符合特定名稱做為交易作業的名稱，搜尋目錄中的檔案或子目錄。

此函式是 FindFirstFileEx 函 式的交易形式。

如需此函式的最基本版本，請參閱 FindFirstFile。

語法

HANDLE FindFirstFileTransactedA(
  [in]  LPCSTR             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 字元) 的字串，或結尾為尾端反斜杠 (\) 。

如果字串以通配符、句號 (.) 或目錄名稱結尾，則用戶必須能夠存取路徑上的根目錄和所有子目錄。

根據預設，名稱限製為MAX_PATH個字元。 若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的一節。

檔案必須位於本機計算機上;否則，函式會失敗，並將最後一個錯誤碼設定為 ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE。

[in] fInfoLevelId

傳回數據的資訊層級。

此參數是其中一個 FINDEX_INFO_LEVELS 列舉值。

[out] lpFindFileData

WIN32_FIND_DATA 結構的指標，可接收所找到檔案或子目錄的相關信息。

[in] fSearchOp

要執行的篩選類型，與通配符比對不同。

此參數是其中一個 FINDEX_SEARCH_OPS 列舉值。

lpSearchFilter

如果指定的 fSearchOp 需要結構化搜尋資訊，則為搜尋準則的指標。

目前，不支援的 fSearchOp 值都不需要擴充搜尋資訊。 因此，此指標必須是 NULL。

[in] dwAdditionalFlags

指定控制搜尋的其他旗標。

值 意義
FIND_FIRST_EX_CASE_SENSITIVE
1
 搜尋會區分大小寫。

[in] hTransaction

交易的句柄。 CreateTransaction 函式會傳回此句柄。

傳回值

如果函式成功，傳回值是搜尋句柄，用於 後續呼叫 FindNextFile 或 FindClose，而 lpFindFileData 參數包含第一個找到之檔案或目錄的相關信息。

如果函式失敗或無法從 lpFileName 參數中的搜尋字串找到檔案，則會 INVALID_HANDLE_VALUE 傳回值，而且 lpFindFileData 的內容不定。 若要取得擴充的錯誤資訊，請呼叫 GetLastError 函 式。

備註

FindFirstFileTransacted 函式會開啟搜尋句柄，並傳回文件系統找到之名稱符合指定模式之第一個檔案的相關信息。 當指定相同的檔名字符串模式時，這可能不是出現在目錄清單應用程式中的第一個檔案或目錄 (，例如 dir 命令) 。 這是因為 FindFirstFileTransacted 不會排序搜尋結果。 如需詳細資訊，請參閱 FindNextFile。

下列清單會識別一些其他搜尋特性：

  • 搜尋會嚴格執行於檔名上，而不是在日期或檔類型等任何屬性上執行。
  • 搜尋包含長和短檔名。
  • 嘗試開啟具有尾端反斜杠的搜尋一律會失敗。
  • 為 lpFileName 參數傳遞無效的字串、NULL 或空字串，不是有效使用此函式。 在此情況下的結果是未定義的。
注意 在罕見的情況下，當您呼叫此函式時，NTFS 檔系統上的檔案資訊可能不是最新的。 若要確保取得目前的檔案資訊，請呼叫 GetFileInformationByHandle 函式。
 
如果基礎文件系統不支援指定的篩選類型，但目錄篩選以外， FindFirstFileTransacted 會失敗，並出現錯誤 ERROR_NOT_SUPPORTED。 應用程式必須使用 FINDEX_SEARCH_OPS 類型 FileExSearchNameMatch 並執行自己的篩選。

建立搜尋句柄之後，請在 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

另請參閱

檔案管理功能

FindClose

FindNextFile

GetFileAttributes

SetFileAttributes

符號連結

交易式 NTFS

WIN32_FIND_DATA