共用方式為

UpdateDriverForPlugAndPlayDevicesW 函式 (newdev.h)

  • 發行項

假設有 INF 檔案和 硬體識別碼， UpdateDriverForPlugAndPlayDevices 函式會為符合硬體識別碼的裝置安裝更新的驅動程式。

語法

BOOL UpdateDriverForPlugAndPlayDevicesW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR HardwareId,
  [in]            LPCWSTR FullInfPath,
  [in]            DWORD   InstallFlags,
  [out, optional] PBOOL   bRebootRequired
);

參數

[in, optional] hwndParent

最上層視窗的句柄，用於任何與安裝裝置相關的UI。

[in] HardwareId

NULL 終止字串的指標，提供硬體識別碼以符合電腦上的現有裝置。 NULL 終止硬體標識碼的最大長度是MAX_DEVICE_ID_LEN。 如需硬體識別碼的詳細資訊，請參閱 裝置識別符字串。

[in] FullInfPath

NULL 終止字串的指標，提供 INF 檔案的完整路徑檔名。 檔案應該位於發佈媒體或廠商建立的目錄中，而不是位於系統位置，例如 %SystemRoot%\inf。 UpdateDriverForPlugAndPlayDevices 會在安裝成功時，將驅動程式檔案複製到適當的系統位置。

[in] InstallFlags

使用 OR 來結合下列零個或多個位旗標所建立的呼叫端提供值：

INSTALLFLAG_FORCE

如果已設定此旗標，且函式找到符合 HardwareId 值的裝置，則函式會為裝置安裝新的驅動程式，指出電腦上是否已有較佳的驅動程式。

重要 請特別小心使用此旗標。 如果使用者在有較新的驅動程式可用之後執行廠商的應用程式，設定此旗標可能會導致較舊的驅動程式安裝在較新的驅動程式上。
 

INSTALLFLAG_READONLY

如果設定此旗標，函式將不會複製、重新命名或刪除任何安裝檔案。 使用此旗標應該受限於限制或不可能存取檔案的環境，例如「內嵌」操作系統。

INSTALLFLAG_NONINTERACTIVE

如果設定此旗標，當偵測到任何嘗試顯示UI時，函式會傳回 FALSE 。 只有在從元件呼叫函式時，才會設定此旗標， (例如無法顯示UI的服務) 。

注意 如果設定此旗標並嘗試UI顯示，裝置可能會處於不確定狀態。
 
InstallFlags 參數通常是零。

[out, optional] bRebootRequired

BOOL 型別變數的指標，指出是否需要重新啟動，以及誰應該提示重新啟動。 此指標是選擇性的，而且可以是 NULL。

如果指標為 NULL，則必要時， UpdateDriverForPlugAndPlayDevices 會在安裝驅動程式之後提示重新啟動。 如果提供指標，函式會傳回 BOOLEAN 值 ，如果應該 重新啟動系統，則傳回 TRUE。 接著，呼叫端必須負責提示重新啟動。

如需詳細資訊，請參閱下列一節。

傳回值

如果裝置升級至指定的驅動程式，此函式會傳回 TRUE 。

否則，它會傳回 FALSE ，而且可以使用 呼叫 GetLastError 來擷取記錄的錯誤。 下表包含 GetLastError 傳回的可能錯誤值。

傳回碼 Description
ERROR_FILE_NOT_FOUND
 針對 FullInfPath 指定的路徑不存在。
ERROR_IN_WOW64
 呼叫的應用程式是在 64 位環境中嘗試執行的 32 位應用程式，不允許此環境。
ERROR_INVALID_FLAGS
 為 InstallFlags 指定的值無效。
ERROR_NO_SUCH_DEVINST
 針對 HardwareId 指定的值不符合系統上的任何裝置。 也就是說，裝置未插入。
ERROR_NO_MORE_ITEMS
 函式發現 HardwareId 值的相符專案，但指定的驅動程式與目前的驅動程式不相符，而且呼叫端未指定INSTALLFLAG_FORCE旗標。

備註

UpdateDriverForPlugAndPlayDevices 會掃描系統上的裝置，並嘗試針對符合指定 HardwareId 值的任何裝置，安裝 FullInfPath 所指定的驅動程式。

默認行為是只有在比目前安裝的驅動程式更符合時，才安裝指定的驅動程式，而且指定的驅動程式也比 %SystemRoot%\inf 中的任何驅動程式更相符。 如需詳細資訊，請參閱 Windows 如何選取驅動程式。

UpdateDriverForPlugAndPlayDevices 也可以用來判斷是否插入具有指定 HardwareId 值的裝置。 如需詳細資訊，請參閱 撰寫裝置安裝應用程式。

UpdateDriverForPlugAndPlayDevices 會將 IRP_MN_QUERY_REMOVE_DEVICE 要求傳送至指定的裝置、裝置的所有子系，以及遞歸屬於裝置移除關聯之其他所有裝置的裝置。 如果上述任何裝置失敗查詢移除要求， UpdateDriverForPlugAndPlayDevices 會在裝置SP_DEVINSTALL_PARAMS結構的 Flags 成員中設定 DI_NEEDREBOOT 旗標。 如需移除關聯的詳細資訊，請參閱 IRP_MN_QUERY_DEVICE_RELATIONS 要求。

一般而言，裝置安裝應用程式應該為 bRebootRequired 提供 NULL。 因此，如有必要，系統會起始重新啟動。 應用程式 應該只在 下列情況下指定指標值：

  • 應用程式必須呼叫 UpdateDriverForPlugAndPlayDevices 數次才能完成安裝。
  • 如果發生) ，應用程式必須在重新啟動 (之前執行其他作業。
  • 應用程式是類別安裝程式，如果需要重新啟動，則應在SP_DEVINSTALL_PARAMS中設定 DI_NEEDREBOOT 。
如果應用程式必須呼叫 UpdateDriverForPlugAndPlayDevices 數次，它應該儲存收到的任何 TRUE 重新啟動狀態值，然後在最後一次呼叫傳回之後提示重新啟動。

如果函式在32位應用程式中傳回ERROR_IN_WOW64，應用程式就會在不允許的64位系統上執行。 如需詳細資訊，請參閱 在64位系統上安裝裝置。

規格需求

需求 值
最低支援的用戶端 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台 桌面
標頭 newdev.h (包含 Newdev.h)
程式庫 Newdev.lib