IDriverEntry：：OnDeviceAdd 方法（wudfddi.h）

發行項
02/07/2025

[警告： UMDF 2 是最新版本的 UMDF，並取代 UMDF 1。所有新的UMDF驅動程式都應該使用UMDF 2撰寫。未將新功能新增至 UMDF 1，而且較新版本的 Windows 10 上對 UMDF 1 的支援有限。通用 Windows 驅動程式必須使用 UMDF 2。如需詳細資訊，請參閱開始使用 UMDF。]

OnDeviceAdd 方法會將新的裝置新增至系統。

語法

HRESULT OnDeviceAdd(
  [in] IWDFDriver           *pWdfDriver,
  [in] IWDFDeviceInitialize *pWdfDeviceInit
);

參數

[in] pWdfDriver

新裝置所屬父驅動程式物件的 IWDFDriver 介面指標。

[in] pWdfDeviceInit

驅動程式用來初始化新建立裝置之 IWDFDeviceInitialize 介面的指標。

傳回值

如果作業成功，OnDeviceAdd 會傳回S_OK。否則，此方法會傳回 Winerror.h 中定義的其中一個錯誤碼。只有當驅動程式成功呼叫 IWDFDriver：：CreateDevice 方法來建立架構裝置物件時，驅動程式才應該傳回S_OK。如果驅動程式傳回錯誤碼，不論驅動程式是篩選驅動程式還是函式驅動程式，UMDF 都會卸除整個裝置堆疊。

言論

系統會針對在驅動程式主機進程中載入的每個裝置建立新的裝置物件。當新的裝置抵達系統時，架構會呼叫 OnDeviceAdd，以通知驅動程序抵達，並傳遞 IWDFDriver 和 IWDFDeviceInitialize 介面。驅動程式可以呼叫 IWDFDeviceInitialize：：RetrieveDevicePropertyStore 方法來查詢裝置安裝時所提供的裝置資訊。驅動程式必須呼叫 IWDFDriver：：CreateDevice 方法來設定和建立裝置。如果驅動程式在傳回S_OK之前未成功呼叫 IWDFDriver：：CreateDevice，UMDF 會判斷驅動程式的行為不正確，並終止主機進程。

任何 OnDeviceAdd 方法傳回S_OK的驅動程式，後續都會在 UMDF 卸除裝置堆疊時收到其 IPnpCallbackHardware：：OnReleaseHardware 方法的呼叫。

請勿使用 IWDFDeviceInitialize 介面，pWdfDeviceInit 參數指向驅動程式呼叫 IWDFDriver：：CreateDevice。

如需詳細資訊，請參閱新增裝置。