Função WlanRegisterNotification (wlanapi.h)

Artigo
01/30/2024

Importante

Algumas informações estão relacionadas a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

A função WlanRegisterNotification é usada para registrar e cancelar o registro de notificações em todas as interfaces sem fio.

Sintaxe

DWORD WlanRegisterNotification(
  [in]            HANDLE                     hClientHandle,
  [in]            DWORD                      dwNotifSource,
  [in]            BOOL                       bIgnoreDuplicate,
  [in, optional]  WLAN_NOTIFICATION_CALLBACK funcCallback,
  [in, optional]  PVOID                      pCallbackContext,
  [in]            PVOID                      pReserved,
  [out, optional] PDWORD                     pdwPrevNotifSource
);

Parâmetros

[in] hClientHandle

O identificador de sessão do cliente, obtido por uma chamada anterior para a função WlanOpenHandle .

[in] dwNotifSource

As fontes de notificação a serem registradas. Esses sinalizadores podem ser combinados. Quando esse parâmetro é definido como WLAN_NOTIFICATION_SOURCE_NONE, WlanRegisterNotification cancela o registro de notificações em todas as interfaces sem fio.

Os valores possíveis para esse parâmetro são definidos nos arquivos de cabeçalho Wlanapi.h e L2cmn.h .

A tabela a seguir mostra os possíveis valores.

Valor	Significado
WLAN_NOTIFICATION_SOURCE_NONE	Cancela o registro de notificações.
WLAN_NOTIFICATION_SOURCE_ALL	Registra todas as notificações disponíveis na versão do sistema operacional, incluindo as geradas pelo módulo 802.1X. Para Windows XP com SP3 e API lan sem fio para Windows XP com SP2, definir dwNotifSource como WLAN_NOTIFICATION_SOURCE_ALL é funcionalmente equivalente a definir dwNotifSource como WLAN_NOTIFICATION_SOURCE_ACM.
WLAN_NOTIFICATION_SOURCE_ACM	Registra as notificações geradas pelo módulo de configuração automática. Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Somente as notificações de wlan_notification_acm_connection_complete e wlan_notification_acm_disconnected estão disponíveis.
WLAN_NOTIFICATION_SOURCE_HNWK	Registra-se para notificações geradas pela rede hospedada sem fio. Essa fonte de notificação está disponível no Windows 7 e no Windows Server 2008 R2 com o Serviço de LAN Sem Fio instalado.
WLAN_NOTIFICATION_SOURCE_ONEX	Registra-se para notificações geradas por 802.1X.
WLAN_NOTIFICATION_SOURCE_MSM	Registra-se para notificações geradas pelo MSM. Se o sinalizador WLAN_NOTIFICATION_SOURCE_MSM estiver definido em dwNotifSource, a funcionalidade do dispositivo wiFiControl será necessária (consulte Declarações de funcionalidade do aplicativo). Se essa funcionalidade não for concedida, a função retornará ERROR_ACCESS_DENIED. Solicitar a funcionalidade do dispositivo wiFiControl exigirá o consentimento do usuário em relação ao acesso ao local. Para obter mais informações, consulte Alterações no comportamento da API para Wi-Fi acesso e localização. Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Não há suporte para esse valor.
WLAN_NOTIFICATION_SOURCE_SECURITY	Registra-se para notificações geradas pelo módulo de segurança. Nenhuma notificação está definida no momento para WLAN_NOTIFICATION_SOURCE_SECURITY. Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Não há suporte para esse valor.
WLAN_NOTIFICATION_SOURCE_IHV	Registra-se para notificações geradas por IHV (fornecedores independentes de hardware). Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Não há suporte para esse valor.
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	Registra-se para notificações geradas pelos serviços de dispositivo.

Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Esse parâmetro deve ser definido como WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL ou WLAN_NOTIFICATION_SOURCE_ACM.

[in] bIgnoreDuplicate

Especifica se as notificações duplicadas serão ignoradas. Se definido como TRUE, uma notificação não será enviada ao cliente se ela for idêntica à anterior.

Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Esse parâmetro é ignorado.

[in, optional] funcCallback

Um tipo de WLAN_NOTIFICATION_CALLBACK que define o tipo de função de retorno de chamada de notificação.

Esse parâmetro poderá ser NULL se o parâmetro dwNotifSource estiver definido como WLAN_NOTIFICATION_SOURCE_NONE para cancelar o registro de notificações em todas as interfaces sem fio,

[in, optional] pCallbackContext

Um ponteiro para o contexto do cliente que será passado para a função de retorno de chamada com a notificação.

[in] pReserved

Reservado para uso futuro. Deve ser definido como NULL.

[out, optional] pdwPrevNotifSource

Um ponteiro para as fontes de notificação registradas anteriormente.

Retornar valor

Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de retorno.

Se o sinalizador WLAN_NOTIFICATION_SOURCE_MSM estiver definido em dwNotifSource, a funcionalidade do dispositivo wiFiControl será necessária (consulte Declarações de funcionalidade do aplicativo). Se essa funcionalidade não for concedida, a função retornará ERROR_ACCESS_DENIED. Solicitar a funcionalidade do dispositivo wiFiControl exigirá o consentimento do usuário em relação ao acesso ao local. Para obter mais informações, consulte Alterações no comportamento da API para Wi-Fi acesso e localização.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se hClientHandle for NULL ou não for válido ou se pReserved não for NULL.
ERROR_INVALID_HANDLE	O identificador hClientHandle não foi encontrado na tabela de identificador.
ERROR_NOT_ENOUGH_MEMORY	Falha ao alocar memória para os resultados da consulta.
ERROR_ACCESS_DENIED	Se o sinalizador WLAN_NOTIFICATION_SOURCE_MSM estiver definido em dwNotifSource, a funcionalidade do dispositivo wiFiControl será necessária (consulte Declarações de funcionalidade do aplicativo. Se essa funcionalidade não for concedida, a função retornará ERROR_ACCESS_DENIED. Solicitar a funcionalidade do dispositivo wiFiControl exigirá o consentimento do usuário em relação ao acesso ao local. Para obter mais informações, consulte Alterações no comportamento da API para Wi-Fi acesso e localização.
RPC_STATUS	Vários códigos de erro.

Comentários

O WlanRegisterNotification é usado por um aplicativo para registrar e cancelar o registro de notificações em todas as interfaces sem fio. Ao se registrar para notificações, um aplicativo deve fornecer uma função de retorno de chamada apontada pelo parâmetro funcCallback . O protótipo dessa função de retorno de chamada é o WLAN_NOTIFICATION_CALLBACK. Essa função de retorno de chamada receberá notificações que foram registradas no parâmetro dwNotifSource passado para a função WlanRegisterNotification . A função de retorno de chamada é chamada com um ponteiro para uma estrutura WLAN_NOTIFICATION_DATA como o primeiro parâmetro que contém informações detalhadas sobre a notificação. A função de retorno de chamada também recebe um segundo parâmetro que contém um ponteiro para o contexto do cliente passado no parâmetro pCallbackContext para a função WlanRegisterNotification .

A função WlanRegisterNotification retornará um erro se dwNotifSource for um valor diferente de WLAN_NOTIFICATION_SOURCE_NONE e o cliente não fornecer uma função de retorno de chamada.

Depois de registrada, a função de retorno de chamada será chamada sempre que uma notificação estiver disponível até que o cliente cancele o registro ou feche o identificador.

Qualquer registro para receber notificações causadas por essa função será desfeito automaticamente se o aplicativo de chamada fechar seu identificador de chamada (chamando WlanCloseHandle com o parâmetro hClientHandle ) ou se o processo terminar.

Não chame WlanRegisterNotification de uma função de retorno de chamada. Se o cliente estiver no meio de um retorno de chamada de notificação quando WlanRegisterNotification for chamado com dwNotifSource definido como WLAN_NOTIFICATION_SOURCE_NONE (ou seja, quando o cliente estiver cancelando o registro de notificações), WlanRegisterNotification aguardará a conclusão do retorno de chamada antes de retornar um valor. Chamar essa função dentro de uma função de retorno de chamada fará com que a chamada nunca seja concluída. Se a função de retorno de chamada e o thread que cancela o registro de notificações tentarem adquirir o mesmo bloqueio, poderá ocorrer um deadlock. Além disso, não chame WlanRegisterNotification da função DllMain em uma DLL do aplicativo. Isso também pode causar um deadlock.

Um aplicativo pode atingir o tempo limite e consultar o estado da interface atual em vez de aguardar uma notificação.

Windows XP com SP3 e API lan sem fio para Windows XP com SP2: As notificações são tratadas pelo serviço Netman. Se o serviço Netman estiver desabilitado ou indisponível, as notificações não serão recebidas. Se uma notificação não for recebida dentro de um período razoável, um aplicativo deverá atingir o tempo limite e consultar o estado da interface atual.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista, Windows XP com SP3 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wlanapi.h (inclua Wlanapi.h)
Biblioteca	Wlanapi.lib
DLL	Wlanapi.dll
Redistribuível	API de LAN sem fio para Windows XP com SP2