Função RegisterDeviceNotificationA (winuser.h)

Artigo
03/11/2023

Registra o dispositivo ou o tipo de dispositivo para o qual uma janela receberá notificações.

Observação

Você pode usar CM_Register_Notification em vez de RegisterDeviceNotification se o código for direcionado Windows 8 ou versões mais recentes do Windows. A vantagem de CM_Register_Notification é que ele não requer um identificador de janela para funcionar.

Sintaxe

HDEVNOTIFY RegisterDeviceNotificationA(
  [in] HANDLE hRecipient,
  [in] LPVOID NotificationFilter,
  [in] DWORD  Flags
);

Parâmetros

[in] hRecipient

Um identificador para a janela ou serviço que receberá eventos de dispositivo para os dispositivos especificados no parâmetro NotificationFilter . O mesmo identificador de janela pode ser usado em várias chamadas para RegisterDeviceNotification.

Os serviços podem especificar um identificador de janela ou um identificador de status de serviço.

[in] NotificationFilter

Um ponteiro para um bloco de dados que especifica o tipo de dispositivo para o qual as notificações devem ser enviadas. Esse bloco sempre começa com a estrutura DEV_BROADCAST_HDR . Os dados que seguem esse cabeçalho dependem do valor do membro dbch_devicetype , que pode ser DBT_DEVTYP_DEVICEINTERFACE ou DBT_DEVTYP_HANDLE. Para obter mais informações, consulte Comentários.

[in] Flags

Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
DEVICE_NOTIFY_WINDOW_HANDLE 0x00000000	O parâmetro hRecipient é um identificador de janela.
DEVICE_NOTIFY_SERVICE_HANDLE 0x00000001	O parâmetro hRecipient é um identificador de status de serviço.

Além disso, você pode especificar o valor a seguir.

Valor	Significado
DEVICE_NOTIFY_ALL_INTERFACE_CLASSES 0x00000004	Notifica o destinatário de eventos de interface do dispositivo para todas as classes de interface do dispositivo. (O membro dbcc_classguid é ignorado.) Esse valor só poderá ser usado se o membro dbch_devicetype for DBT_DEVTYP_DEVICEINTERFACE.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador de notificação do dispositivo.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Os aplicativos enviam notificações de eventos usando a função BroadcastSystemMessage . Qualquer aplicativo com uma janela de nível superior pode receber notificações básicas processando a mensagem WM_DEVICECHANGE . Os aplicativos podem usar a função RegisterDeviceNotification para se registrar para receber notificações do dispositivo.

Os serviços podem usar a função RegisterDeviceNotification para se registrar para receber notificações do dispositivo. Se um serviço especificar um identificador de janela no parâmetro hRecipient , as notificações serão enviadas para o procedimento de janela. Se hRecipient for um identificador de status de serviço, SERVICE_CONTROL_DEVICEEVENT notificações serão enviadas ao manipulador de controle de serviço. Para obter mais informações sobre o manipulador de controle de serviço, consulte HandlerEx.

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

Os identificadores de notificação de dispositivo retornados por RegisterDeviceNotification devem ser fechados chamando a função UnregisterDeviceNotification quando eles não forem mais necessários.

Os eventos DBT_DEVICEARRIVAL e DBT_DEVICEREMOVECOMPLETE são transmitidos automaticamente para todas as janelas de nível superior para dispositivos de porta. Portanto, não é necessário chamar RegisterDeviceNotification para portas e a função falhará se o membro dbch_devicetype for DBT_DEVTYP_PORT. As notificações por volume também são transmitidas para janelas de nível superior, portanto, a função falhará se dbch_devicetype for DBT_DEVTYP_VOLUME. Os dispositivos definidos pelo OEM não são usados diretamente pelo sistema, portanto, a função falhará se dbch_devicetype for DBT_DEVTYP_OEM.

Exemplos

Para obter um exemplo, consulte Registrando-se para notificação de dispositivo.

Observação

O cabeçalho winuser.h define RegisterDeviceNotification como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP
Servidor mínimo com suporte	Windows Server 2003
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-misc-l1-1-0 (introduzido no Windows 8)