SetupGetFileCompressionInfoA 函式 (setupapi.h)

發行項
03/05/2024

[此函式可用於需求一節中所述的操作系統。它在後續版本中可能會變更或無法使用。安裝程式API不應再用於安裝應用程式。請改用 Windows Installer 來開發應用程式安裝程式。 SetupAPI 會繼續用於安裝設備驅動器。]

SetupGetFileCompressionInfo 函式會檢查實體檔案，以判斷它是否已壓縮並取得其完整路徑、大小和未壓縮目標檔案的大小。

請注意，此函式已過時，且已由 SetupGetFileCompressionInfoEx 取代。請勿使用 SetupGetFileCompressionInfo，而是一律使用 SetupGetFileCompressionInfoEx。

語法

WINSETUPAPI DWORD SetupGetFileCompressionInfoA(
  [in]      PCSTR  SourceFileName,
  [in, out] PSTR   *ActualSourceFileName,
  [in, out] PDWORD SourceFileSize,
  [in, out] PDWORD TargetFileSize,
  [in, out] PUINT  CompressionType
);

參數

[in] SourceFileName

所需資訊之檔案的檔名。如果來源媒體上找不到檔案，則檔案會搜尋最多兩個替代的「壓縮格式」名稱。例如，如果檔案 F:\x86\cmd.exe 且找不到，則會搜尋 F：\mpis\cmd.ex_，如果找不到，則會搜尋 F：\x86\cmd.ex$。您應該使用以 Null 結尾的字串。

[in, out] ActualSourceFileName

變數的指標，該變數會接收其能夠找到之檔案的完整路徑。呼叫端可以使用 LocalFree的呼叫來釋放指標。只有在函式傳回NO_ERROR時，路徑才有效。請注意，如果 SetupAPI.dll 的版本小於 5.0.2195，則呼叫端必須從 SetupAPI 使用導出的 函式 MyFree 來釋放此函式所配置的記憶體，而不是使用 LocalFree。請參閱＜備註＞一節。

[in, out] SourceFileSize

變數的指標，此變數會傳回其目前格式的檔案大小，這是 ActualSourceFileName 所命名之檔案的目前大小。大小是由檢查來源檔案來決定;它不會從 INF 檔案中擷取。只有在函式傳回NO_ERROR時，原始程序檔大小才有效。

[in, out] TargetFileSize

變數的指標，此變數會傳回檔案未壓縮或複製時所佔用的大小。如果檔案未壓縮，此值將會與 SourceFileSize相同。大小是由檢查檔案來決定;它不會從 INF 檔案中擷取。只有在函式傳回NO_ERROR時，目標檔案大小才有效。

[in, out] CompressionType

變數的指標，此函式會傳回值，指出 ActualSourceFileName 所使用的壓縮類型。只有在函式傳回NO_ERROR時，壓縮類型才有效。此值可以是下列其中一個旗標。

FILE_COMPRESSION_NONE

來源檔案不會使用辨識的壓縮演算法進行壓縮。

FILE_COMPRESSION_WINLZA

原始程式檔會使用 LZ 壓縮進行壓縮。

FILE_COMPRESSION_MSZIP

來源檔案會使用 MSZIP 壓縮進行壓縮。

傳回值

函式會傳回系統錯誤碼，指出檔案搜尋的結果。錯誤碼可以是下列其中一個值。

若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

請勿使用 SetupGetFileCompressionInfo，而是一律使用 SetupGetFileCompressionInfoEx。

由於 SetupGetFileCompressionInfo 藉由參考實體檔案來決定壓縮，所以安裝應用程式應該先確定檔案存在，再呼叫 SetupGetFileCompressionInfo。

請注意，如果 SetupAPI.dll 的版本小於 5.0.2195，則呼叫端必須從 SetupAPI 使用導出的 函式 MyFree 來釋放此函式所配置的記憶體，而不是使用 LocalFree。如果呼叫 LocalFree 會造成存取違規，您應該使用 MyFree 解決問題。

以下是如何從 SetupAPI.dll 取得 MyFree 函式的範例：

typedef VOID (WINAPI* MYFREEFUNC)(LPVOID lpBuff);
   MYFREEFUNC MyFree;

   HMODULE hDll=NULL;
   hDll = GetModuleHandle("SETUPAPI.DLL");
   MyFree = (MYFREEFUNC)GetProcAddress(hDll, "MyFree");
   ...
   other code here to prepare file queue
   ...
   PTSTR lpActualSourceFileName;
   SetupGetFileCompressionInfo(...,&lpActualSourceFileName,...,...,...);
   ...
   MyFree(lpActualSourceFileName);

注意

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

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	setupapi.h
程式庫	Setupapi.lib
Dll	Setupapi.dll