función CM_Register_Notification (cfgmgr32.h)

Artículo
08/22/2023

La función CM_Register_Notification registra una rutina de devolución de llamada de aplicación que se llamará cuando se produce un evento PnP del tipo especificado.

Usa RegisterDeviceNotification en lugar de CM_Register_Notification si el código tiene como destino Windows 7 o versiones anteriores de Windows. En su lugar, los autores de llamadas en modo kernel deben usar IoRegisterPlugPlayNotification .

Sintaxis

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

Parámetros

[in] pFilter

Puntero a una estructura de CM_NOTIFY_FILTER .

[in, optional] pContext

Puntero a un búfer asignado por el autor de la llamada que contiene el contexto que se va a pasar a la rutina de devolución de llamada en pCallback.

[in] pCallback

Puntero a la rutina que se va a llamar cuando se produce el evento PnP especificado. Consulte la sección Comentarios del prototipo de la función de devolución de llamada.

El parámetro Action de la rutina de devolución de llamada será un valor de la enumeración CM_NOTIFY_ACTION .

Tras recibir una notificación, el modo en que la devolución de llamada examina la notificación dependerá del miembro FilterType del parámetro EventData de la rutina de devolución de llamada:

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

La devolución de llamada debe examinar EventData-u.DeviceInterface>.

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

La devolución de llamada debe examinar EventData-u.DeviceHandle>.

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

La devolución de llamada debe examinar EventData-u.DeviceInstance>.

[out] pNotifyContext

Puntero para recibir el identificador HCMNOTIFICATION que corresponde a la llamada de registro.

Valor devuelto

Si la operación se realiza correctamente, la función devuelve CR_SUCCESS. De lo contrario, devuelve uno de los códigos de error con prefijo CR_ definidos en Cfgmgr32.h.

Comentarios

Asegúrese de controlar Plug and Play eventos de dispositivo lo antes posible. Si el controlador de eventos realiza cualquier operación que pueda bloquear la ejecución (por ejemplo, E/S), es mejor iniciar otro subproceso para realizar la operación de forma asincrónica.

La función CM_Register_Notification no proporciona notificación de las interfaces de dispositivo existentes. Para recuperar las interfaces existentes, llame primero a CM_Register_Notification y, a continuación, llame a CM_Get_Device_Interface_List. Si la interfaz está habilitada después de que el controlador llame a CM_Register_Notification, pero antes de que el controlador llame a CM_Get_Device_Interface_List, el controlador recibe una notificación para la llegada de la interfaz y la interfaz también aparece en la lista de instancias de interfaz de dispositivo devueltas por CM_Get_Device_Interface_List.

Los identificadores HCMNOTIFICATION devueltos por CM_Register_Notification deben cerrarse llamando a la función CM_Unregister_Notification cuando ya no se necesiten.

Una rutina de devolución de llamada usa el siguiente prototipo de función:

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
    );

Si responde a una notificación de CM_NOTIFY_ACTION_DEVICEQUERYREMOVE , la devolución de llamada PCM_NOTIFY_CALLBACK debe devolver ERROR_SUCCESS o ERROR_CANCELLED, según corresponda. De lo contrario, la devolución de llamada debe devolver ERROR_SUCCESS. La devolución de llamada no debe devolver ningún otro valor. Para obtener una descripción de otras acciones, consulte la documentación de CM_NOTIFY_ACTION . Consulte también CM_NOTIFY_EVENT_DATA para obtener información sobre la estructura que recibe esta devolución de llamada en el parámetro EventData .

Ejemplos

Para obtener un ejemplo, consulte Registro para la notificación de la llegada de la interfaz de dispositivo y eliminación de dispositivos.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Microsoft Windows 8 y versiones posteriores de Windows.
Plataforma de destino	Universal
Encabezado	cfgmgr32.h (incluya Cfgmgr32.h)
Library	Cfgmgr32.lib; OneCoreUAP.lib en Windows 10
Archivo DLL	CfgMgr32.dll