функция CM_Register_Notification (cfgmgr32.h)

Статья
02/28/2024

Функция CM_Register_Notification регистрирует подпрограмму обратного вызова приложения для вызова при возникновении события PnP указанного типа.

Используйте RegisterDeviceNotification вместо CM_Register_Notification , если ваш код предназначен для Windows 7 или более ранних версий Windows. Вызывающие операторы режима ядра должны использовать 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 .

То, как обратный вызов проверяет уведомление, будет зависеть от элемента FilterType параметра EventData подпрограммы обратного вызова:

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. В противном случае возвращается один из кодов ошибок с CR_ префиксами, определенных в Cfgmgr32.h.

Не забудьте как можно быстрее обрабатывать события Plug and Play устройства. Если обработчик событий выполняет какие-либо операции, которые могут блокировать выполнение (например, операции ввода-вывода), лучше запустить другой поток, чтобы выполнить операцию асинхронно.

Функция CM_Register_Notification не предоставляет уведомления о существующих интерфейсах устройств. Чтобы получить существующие интерфейсы, сначала вызовите CM_Register_Notification, а затем вызовите CM_Get_Device_Interface_List. Если интерфейс включен после того, как драйвер вызывает CM_Register_Notification, но до того, как драйвер вызывает CM_Get_Device_Interface_List, драйвер получает уведомление о поступлении интерфейса, и интерфейс также отображается в списке экземпляров интерфейса устройства, возвращенных CM_Get_Device_Interface_List.

Дескриптора HCMNOTIFICATION, возвращаемые CM_Register_Notification , должны быть закрыты путем вызова функции 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 . Сведения о структуре, получаемой этим обратным вызовом в параметре EventData, см. также в CM_NOTIFY_EVENT_DATA.

Примеры

Пример см. в разделе Регистрация для уведомления о поступлении и удалении интерфейса устройства.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Microsoft Windows 8 и более поздних версиях Windows.
Целевая платформа	Универсальное
Верхняя часть	cfgmgr32.h (включая Cfgmgr32.h)
Библиотека	Cfgmgr32.lib; OneCoreUAP.lib в Windows 10
DLL	CfgMgr32.dll