CM_Register_Notification函式 (cfgmgr32.h)

發行項
03/13/2024

CM_Register_Notification函式會在發生指定類型的 PnP 事件時註冊要呼叫的應用程式回呼例程。

如果您的程式代碼是以 Windows 7 或舊版 Windows 為目標，請使用 RegisterDeviceNotification ，而不是 CM_Register_Notification 。核心模式呼叫端應該改用 IoRegisterPlugPlayNotification 。

語法

CMAPI CONFIGRET CM_Register_Notification(
  [in]           PCM_NOTIFY_FILTER   pFilter,
  [in, optional] PVOID               pContext,
  [in]           PCM_NOTIFY_CALLBACK pCallback,
  [out]          PHCMNOTIFICATION    pNotifyContext
);

參數

[in] pFilter

CM_NOTIFY_FILTER 結構的指標。

[in, optional] pContext

呼叫端配置的緩衝區指標，其中包含要在 pCallback 中傳遞至回呼例程的內容。

[in] pCallback

當指定的 PnP 事件發生時，要呼叫之例程的指標。如需回呼函式的原型，請參閱一節。

回呼例程的 Action 參數將是來自CM_NOTIFY_ACTION 列舉的值。

收到通知時，回呼檢查通知的方式取決於回呼例程 EventData 參數的 FilterType 成員：

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

回呼應該檢查 EventData-u.DeviceInterface>。

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

回呼應該會檢查 EventData-u.DeviceHandle>。

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

回呼應該檢查 EventData-u.DeviceInstance>。

[out] pNotifyContext

接收對應至註冊呼叫之 HCMNOTIFICATION 句柄的指標。

傳回值

如果作業成功，函式會傳回CR_SUCCESS。否則，它會傳回 Cfgmgr32.h 中定義的其中一個CR_前置錯誤碼。

備註

請務必儘快處理隨插即用裝置事件。如果您的事件處理程式執行任何可能會封鎖執行 (的作業，例如 I/O) ，最好以異步方式啟動另一個線程來執行作業。

CM_Register_Notification函式不提供現有裝置介面的通知。若要擷取現有的介面，請先呼叫 CM_Register_Notification，然後呼叫 CM_Get_Device_Interface_List。如果在驅動程式呼叫CM_Register_Notification之後啟用介面，但在驅動程式呼叫CM_Get_Device_Interface_List之前，驅動程式會收到介面抵達的通知，而且介面也會出現在CM_Get_Device_Interface_List傳回的裝置介面實例清單中。

CM_Register_Notification傳回的 HCMNOTIFICATION 句柄必須在不再需要時呼叫 CM_Unregister_Notification 函式來關閉。

回呼例程使用下列函式原型：

typedef __callback DWORD (CALLBACK *PCM_NOTIFY_CALLBACK)(
    _In_ HCMNOTIFICATION       hNotify,
    _In_opt_ PVOID             Context,
    _In_ CM_NOTIFY_ACTION      Action,
    _In_reads_bytes_(EventDataSize) PCM_NOTIFY_EVENT_DATA EventData,
    _In_ DWORD                 EventDataSize
    );

如果回應 CM_NOTIFY_ACTION_DEVICEQUERYREMOVE 通知，PCM_NOTIFY_CALLBACK回呼應該視需要傳回ERROR_SUCCESS或ERROR_CANCELLED。否則，回呼應該會傳回ERROR_SUCCESS。回呼不應該傳回任何其他值。如需其他動作的描述，請參閱 CM_NOTIFY_ACTION 檔。另請參閱 CM_NOTIFY_EVENT_DATA ，以取得此回呼在 EventData 參數中接收之結構的相關信息。

範例

如需範例，請參閱註冊裝置介面抵達和裝置移除通知。

規格需求

需求	值
最低支援的用戶端	可在 Microsoft Windows 8 和更新版本的 Windows 中使用。
目標平台	Universal
標頭	cfgmgr32.h (包含 Cfgmgr32.h)
程式庫	Cfgmgr32.lib;Windows 10 上的 OneCoreUAP.lib
Dll	CfgMgr32.dll