共用方式為

SetupScanFileQueueA 函式 (setupapi.h)

  • 發行項

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

SetupScanFileQueue 函式會掃描安裝程式檔案佇列，並在其複製清單中的每個節點上執行作業。 作業是由一組旗標所指定。 您可以在認可佇列之前或之後呼叫此函式。

語法

WINSETUPAPI BOOL SetupScanFileQueueA(
  [in]  HSPFILEQ            FileQueue,
  [in]  DWORD               Flags,
  [in]  HWND                Window,
  [in]  PSP_FILE_CALLBACK_A CallbackRoutine,
  [in]  PVOID               CallbackContext,
  [out] PDWORD              Result
);

參數

[in] FileQueue

處理要掃描或逐一查看其複製清單的安裝程式檔案佇列。

[in] Flags

要結合以控制檔案佇列掃描作業的旗標。 請注意，必須指定SPQ_SCAN_FILE_PRESENCE、SPQ_SCAN_USE_CALLBACK、SPQ_SCAN_USE_CALLBACKEX或SPQ_SCAN_FILE_VALIDITY。

旗標 意義
SPQ_SCAN_FILE_PRESENCE
 複製佇列中的目標檔案已存在於目標上。
SPQ_SCAN_FILE_VALIDITY
 複製佇列中的目標檔案已存在於具有有效簽章的目標上。 適用於 Windows 2000 和更新版本。
SPQ_SCAN_USE_CALLBACK
 佇列中每個節點的回呼例程。 如果回呼例程傳回非零值，佇列處理會停止， 而 SetupScanFileQueue 會傳回零。 發出 SPFILENOTIFY_QUEUESCAN 通知程序代碼，並將指標傳遞至目標路徑做為 Param1。
SPQ_SCAN_USE_CALLBACKEX
 佇列中每個節點的回呼例程。 如果回呼例程傳回非零值，佇列處理會停止， 而 SetupScanFileQueue 會傳回零。 發出SPFILENOTIFY_QUEUESCAN_EX通知，並將指標傳遞至 FILEPATHS 結構做為 Param1。 SPQ_SCAN_USE_CALLBACKEX也會檢查檔案是否具有有效的簽章。 從 Windows 2000 開始提供。 僅限 Windows XP，您可以結合此旗標與SPQ_SCAN_FILE_PRESENCE來關閉簽章檢查。
SPQ_SCAN_INFORM_USER
 當佇列中的所有檔案都通過有效簽章檢查時所指定的旗標。 SetupScanFileQueue 會通知用戶作業需要目標上已存在的檔案。 如果未指定SPQ_SCAN_FILE_PRESENCE或SPQ_SCAN_FILE_VALIDITY，則會忽略此旗標。 此旗標不能與SPQ_SCAN_PRUNE_COPY_QUEUE或SPQ_SCAN_PRUNE_DELREN搭配使用。
SPQ_SCAN_PRUNE_COPY_QUEUE
 與SPQ_SCAN_FILE_PRESENCE結合，會從複製佇列中移除現有專案。 與SPQ_SCAN_FILE_VALIDITY結合時，會從複製佇列中移除帶正負號的專案。 從 Windows 2000 開始提供。 僅在 Windows XP 上，除非指定刪除佇列或重新命名佇列中指定的檔案，否則不會剪除SPQ_SCAN_PRUNE_DELREN。
SPQ_SCAN_USE_CALLBACK_SIGNERINFO
 從 Windows XP 開始提供。 通知SPFILENOTIFY_QUEUESCAN_SIGNERINFO問題，並將指標以 Param1 的形式傳遞至FILEPATHS_SIGNERINFO結構。 檢查每個檔案是否有有效的簽章，並透過回調函式報告簽章資訊。
SPQ_SCAN_PRUNE_DELREN
 與SPQ_SCAN_FILE_PRESENCE或SPQ_SCAN_FILE_VALIDITY結合，移除同時位於複製佇列中的刪除或重新命名佇列中的專案。 與SPQ_SCAN_PRUNE_COPY_QUEUE結合時，會將從複製佇列中移除的檔案限製為不在刪除或重新命名佇列中的檔案。 從 Windows XP 開始提供。

[in] Window

視窗的選擇性句柄，以擁有所呈現的對話框。 如果 Flags 參數不包含SPQ_SCAN_FILE_PRESENCE或 Flags 不包含SPQ_SCAN_INFORM_USER，則不會使用此參數。

[in] CallbackRoutine

要在複製佇列的每個節點上呼叫 之 FileCallback 回 呼函式的選擇性指標。 傳遞至回調函式的通知程式碼 SPFILENOTIFY_QUEUESCAN。 如果 Flags 包含 SPQ_SCAN_USE_CALLBACK，則需要此參數。

注意 您必須提供 CallbackRoutine 指定的回呼例程。 默認佇列回呼例程不支援 SetupScanFileQueue。
 

[in] CallbackContext

內容的選擇性指標，其中包含傳遞至 CallbackRoutine 所指向之回呼例程的呼叫端定義數據。

[out] Result

接收掃描作業結果的變數指標。

傳回值

如果已處理佇列中的所有節點，此函式會傳回非零值。

如果已設定SPQ_SCAN_USE_CALLBACK旗標， 則 Result 中的值為 0。 CallbackRoutine 指定的回呼例程會傳送通知SPFILENOTIFY_QUEUESCAN。 CallbackRoutine.Param1 指定包含目標路徑資訊的陣列指標。 指標已轉換成不帶正負號的整數，而且必須先重新轉換成MAX_PATH元素的 TCHAR 陣列，回呼例程才能存取資訊。 CallbackRoutine.Param2 設定為 SPQ_DELAYED_COPY目前的佇列節點正在使用中，而且在系統重新啟動之前無法複製。 否則， CallbackRoutine.Param2 會接受值 0。

如果未設定 SPQ_SCAN_USE_CALLBACK，Result 會指出佇列是否已通過目前狀態或有效性檢查，如下表所示。

傳回碼 描述
0
 佇列失敗檢查或通過檢查，但已指定SPQ_SCAN_INFORM_USER，且使用者想要新的檔案複本。
1
 佇列通過檢查，如果指定了SPQ_SCAN_INFORM_USER，使用者表示不需要複製。 複製佇列是空的，而且刪除或重新命名佇列上沒有元素，因此呼叫端可以略過佇列認可。
2
 佇列通過檢查，如果指定了SPQ_SCAN_INFORM_USER，使用者表示不需要複製。 複製佇列是空的，但刪除或重新命名佇列上有元素，因此呼叫端無法略過佇列認可。
 

如果發生錯誤，或回呼函式傳回非零值，則函式會傳回零。 如果 Result 為非零，則為停止佇列處理的回調函式所傳回的值。 如果 Result 為零，則可以呼叫 GetLastError 來擷取擴充錯誤資訊。

備註

注意

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

規格需求

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

另請參閱

FileCallback

函式

概觀

SetupCommitFileQueue

SetupDefaultQueueCallback