función CM_Register_Notification (cfgmgr32.h)
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 |