função CM_Register_Notification (cfgmgr32.h)

Artigo
03/08/2023

A função CM_Register_Notification registra uma rotina de retorno de chamada do aplicativo a ser chamada quando ocorre um evento PnP do tipo especificado.

Use RegisterDeviceNotification em vez de CM_Register_Notification se o código for direcionado ao Windows 7 ou versões anteriores do Windows. Os chamadores do modo kernel devem usar IoRegisterPlugPlayNotification .

Sintaxe

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

Ponteiro para uma estrutura CM_NOTIFY_FILTER .

[in, optional] pContext

Ponteiro para um buffer alocado pelo chamador que contém o contexto a ser passado para a rotina de retorno de chamada no pCallback.

[in] pCallback

Ponteiro para a rotina a ser chamada quando o evento PnP especificado ocorrer. Consulte a seção Comentários para obter o protótipo da função de retorno de chamada.

O parâmetro Action da rotina de retorno de chamada será um valor da enumeração CM_NOTIFY_ACTION .

Ao receber uma notificação, como o retorno de chamada examina a notificação dependerá do membro FilterType do parâmetro EventData da rotina de retorno de chamada:

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

O retorno de chamada deve examinar EventData-u.DeviceInterface>.

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

O retorno de chamada deve examinar EventData-u.DeviceHandle>.

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

O retorno de chamada deve examinar EventData-u.DeviceInstance>.

[out] pNotifyContext

Ponteiro para receber o identificador HCMNOTIFICATION que corresponde à chamada de registro.

Retornar valor

Se a operação for bem-sucedida, a função retornará CR_SUCCESS. Caso contrário, ele retornará um dos códigos de erro prefixados por CR_ definidos em Cfgmgr32.h.

Comentários

Certifique-se de lidar com Plug and Play eventos de dispositivo o mais rápido possível. Se o manipulador de eventos executar qualquer operação que possa bloquear a execução (como E/S), é melhor iniciar outro thread para executar a operação de forma assíncrona.

A função CM_Register_Notification não fornece notificação de interfaces de dispositivo existentes. Para recuperar interfaces existentes, primeiro chame CM_Register_Notification e chame CM_Get_Device_Interface_List. Se a interface estiver habilitada após o driver chamar CM_Register_Notification, mas antes que o driver chame CM_Get_Device_Interface_List, o driver receberá uma notificação para a chegada da interface e a interface também aparecerá na lista de instâncias de interface do dispositivo retornadas por CM_Get_Device_Interface_List.

Os identificadores HCMNOTIFICATION retornados por CM_Register_Notification devem ser fechados chamando a função CM_Unregister_Notification quando eles não forem mais necessários.

Uma rotina de retorno de chamada usa o seguinte protótipo de função:

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

Se responder a uma notificação de CM_NOTIFY_ACTION_DEVICEQUERYREMOVE , o retorno de chamada PCM_NOTIFY_CALLBACK deverá retornar ERROR_SUCCESS ou ERROR_CANCELLED, conforme apropriado. Caso contrário, o retorno de chamada deverá retornar ERROR_SUCCESS. O retorno de chamada não deve retornar nenhum outro valor. Para obter uma descrição de outras ações, consulte a documentação do CM_NOTIFY_ACTION . Consulte também CM_NOTIFY_EVENT_DATA para obter informações sobre a estrutura que esse retorno de chamada recebe no parâmetro EventData .

Exemplos

Para obter um exemplo, consulte Registrando-se para notificação de chegada da interface do dispositivo e remoção de dispositivo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Microsoft Windows 8 e versões posteriores do Windows.
Plataforma de Destino	Universal
Cabeçalho	cfgmgr32.h (inclua Cfgmgr32.h)
Biblioteca	Cfgmgr32.lib; OneCoreUAP.lib no Windows 10
DLL	CfgMgr32.dll