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 寬字元，請在路徑前面加上 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間。

[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。

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

• 搜尋會嚴格執行於檔名上，而不是在日期或檔類型等任何屬性上執行。
• 搜尋包含長和短檔名。
• 嘗試開啟具有尾端反斜杠的搜尋一律會失敗。
• 傳遞無效的字串、NULL或 lpFileName 參數的空字串，不是這個函式的有效用法。 在此情況下，結果為未定義。

建立搜尋句柄之後，請在 findNextFile 函式 使用它，搜尋符合相同模式的其他檔案，以及正在執行的相同篩選。 不需要搜尋句柄時，應該使用 FindClose 函式來關閉它。

如先前所述，您無法在 lpFileName 輸入字串中使用尾端反斜杠 （\）， FindFirstFileTransacted，因此搜尋根目錄可能並不明顯。 如果您想要檢視檔案或取得根目錄的屬性，適用下列選項：

• 若要檢查根目錄中的檔案，您可以使用 「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，並在最後一次呼叫 FindNextFile之後呼叫 Wow64RevertWow64FsRedirection 。 如需詳細資訊，請參閱 檔案系統重新導向器。

如果路徑指向符號連結，則 WIN32_FIND_DATA 緩衝區包含符號連結的相關信息，而不是目標。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此功能。

SMB 3.0 不支援 TxF。

要求

另請參閱

檔案管理功能

FindClose

FindNextFile

GetFileAttributes

SetFileAttributes

符號連結

交易式NTFS

WIN32_FIND_DATA