VerFindFileA 函式 (winver.h)

發行項
03/04/2024

根據檔案在系統中找到另一個版本的檔案，判斷安裝檔案的位置。 VerFindFile 傳回的值會在後續呼叫 VerInstallFile 函式時使用。

語法

DWORD VerFindFileA(
  [in]           DWORD  uFlags,
  [in]           LPCSTR szFileName,
  [in, optional] LPCSTR szWinDir,
  [in]           LPCSTR szAppDir,
  [out]          LPSTR  szCurDir,
  [in, out]      PUINT  puCurDirLen,
  [out]          LPSTR  szDestDir,
  [in, out]      PUINT  puDestDirLen
);

參數

[in] uFlags

類型： DWORD

此參數可以是下列值。所有其他位都會保留。

值	意義
VFFF_ISSHAREDFILE 0x0001	來源檔案可由多個應用程式共用。應用程式可以使用這項資訊來判斷應該複製檔案的位置。

[in] szFileName

類型： LPCTSTR

要安裝的檔名。只包含檔名和擴展名，而非路徑。

[in, optional] szWinDir

類型： LPCTSTR

執行 Windows 或將執行的目錄。 GetWindowsDirectory 函式會傳回此字串。

[in] szAppDir

類型： LPCTSTR

安裝程式安裝一組相關檔案的目錄。如果安裝程式正在安裝應用程式，這是應用程式所在的目錄。除非另有指定，否則此參數也會指向應用程式的目前目錄。

[out] szCurDir

類型： LPWSTR

緩衝區，接收所安裝檔案目前版本的路徑。路徑是以零結尾的字串。如果未安裝目前的版本，緩衝區將包含零長度字串。緩衝區長度至少應 _MAX_PATH 個字元，但並非必要。

[in, out] puCurDirLen

類型： PUINT

szCurDir 緩衝區的長度。此指標不得為 NULL。

當函式傳回時， lpuCurDirLen 包含 szCurDir 中傳回之數據的大小，包括終止 Null 字元。如果緩衝區太小而無法包含所有數據， lpuCurDirLen 將會是保存路徑所需的緩衝區大小。

[out] szDestDir

類型： LPTSTR

緩衝區，接收 VerFindFile 所建議安裝位置的路徑。路徑是以零結尾的字串。緩衝區長度至少應 _MAX_PATH 個字元，但並非必要。

[in, out] puDestDirLen

類型： PUINT

指定 szDestDir 緩衝區長度之變數的指標。此指標不得為 NULL。

當函式傳回時， lpuDestDirLen 包含 szDestDir 中所傳回數據的大小，包括終止 Null 字元。如果緩衝區太小而無法包含所有數據， lpuDestDirLen 將會是保存路徑所需的緩衝區大小。

傳回值

類型： DWORD

傳回值是位掩碼，表示檔案的狀態。它可以是下列一或多個值。所有其他值都會保留。

傳回碼/值	Description
VFF_CURNEDEST 0x0001	目前安裝的檔案版本不在建議的目的地中。
VFF_FILEINUSE 0x0002	系統正在使用目前安裝的檔案版本;因此，無法覆寫或刪除檔案。
VFF_BUFFTOOSMALL 0x0004	至少有一個緩衝區太小而無法包含對應的字串。應用程式應該檢查輸出緩衝區，以判斷哪個緩衝區太小。

備註

此函式適用於16位、32位和64位檔案映像。

VerFindFile 會使用 OpenFile 函式搜尋指定檔案的複本。不過，它會從指定的 Windows 目錄判斷系統目錄，或搜尋路徑。

如果 dwFlags 參數指出此應用程式 (沒有VFFF_ISSHAREDFILE) ，VerFindFile 建議在應用程式的目錄中安裝檔案。否則，如果系統正在執行系統的共用複本，函式建議在 Windows 目錄中安裝檔案。如果系統正在執行系統的私用複本，函式建議在系統目錄中安裝檔案。

注意

winver.h 標頭會將 VerFindFile 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winver.h (包括 Windows.h)
程式庫	Version.lib
Dll	Api-ms-win-core-version-l1-1-0.dll