Função WlanScan (wlanapi.h)

Artigo
03/04/2024

Observação

Algumas informações relacionam-se ao produto de pré-lançamento, o qual poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Importante

Essa API será afetada pelas próximas alterações no comportamento do sistema operacional, previstas para o outono de 2024. Para obter mais informações, consulte Alterações no comportamento da API para Wi-Fi acesso e localização.

A função WlanScan solicita uma verificação de redes disponíveis na interface indicada.

Sintaxe

DWORD WlanScan(
  [in]           HANDLE               hClientHandle,
  [in]           const GUID           *pInterfaceGuid,
  [in, optional] const PDOT11_SSID    pDot11Ssid,
  [in, optional] const PWLAN_RAW_DATA pIeData,
                 PVOID                pReserved
);

Parâmetros

[in] hClientHandle

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

[in] pInterfaceGuid

O GUID da interface a ser consultada.

O GUID de cada interface lan sem fio habilitada em um computador local pode ser determinado usando a função WlanEnumInterfaces .

[in, optional] pDot11Ssid

Um ponteiro para uma estrutura DOT11_SSID que especifica o SSID da rede a ser verificada. Esse parâmetro é opcional. Quando definida como NULL, a lista retornada contém todas as redes disponíveis. Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Esse parâmetro deve ser NULL.

[in, optional] pIeData

Um ponteiro para um elemento de informações a ser incluído em solicitações de investigação. Esse parâmetro aponta para uma estrutura de WLAN_RAW_DATA que pode incluir informações de disponibilidade de provisionamento de cliente e requisitos de autenticação 802.1X. Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Esse parâmetro deve ser NULL.

pReserved

Reservado para uso futuro. Deve ser definido como NULL.

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.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	hClientHandle é NULL ou inválido, pInterfaceGuid é NULL ou pReserved não é NULL.
ERROR_INVALID_HANDLE	O identificador hClientHandle não foi encontrado na tabela de identificador.
RPC_STATUS	Vários códigos de erro.
ERROR_NOT_ENOUGH_MEMORY	Falha ao alocar memória para os resultados da consulta.

Comentários

A função WlanScan solicita que o driver de LAN sem fio nativo 802.11 verifique se há redes sem fio disponíveis. O driver pode ou não enviar solicitações de investigação (uma verificação ativa) dependendo de sua implementação e dos valores passados nos parâmetros pDot11Ssid e pIeData .

Se o parâmetro pIeData não for NULL, o driver enviará solicitações de investigação durante a verificação. As solicitações de investigação incluem o elemento de informações (IE) apontado pelo parâmetro pIeData . Por exemplo, o IE do WPS (instalação protegida Wi-Fi) pode ser incluído nas solicitações de investigação para descobrir pontos de acesso compatíveis com WPS. O buffer apontado pelo parâmetro pIeData deve conter o IE completo a partir da ID do elemento.

O parâmetro pIeData passado para a função WlanScan pode conter um ponteiro para uma estrutura de WLAN_RAW_DATA opcional que contém uma entrada de dados do IE (descoberta de serviço de proximidade).

Quando usado para armazenar um IE PSD, a constante DOT11_PSD_IE_MAX_DATA_SIZE definida no arquivo de cabeçalho Wlanapi.h é o valor máximo do membro dwDataSize .

Constante	Valor	Descrição
DOT11_PSD_IE_MAX_DATA_SIZE	240	O tamanho máximo dos dados, em bytes, de uma entrada de dados do PSD IE.

Para obter mais informações sobre IEs PSD, incluindo uma discussão sobre o formato de um IE PSD, consulte a função WlanSetPsdIEDataList .

Quando a função WlanScan é chamada, o driver lan sem fio nativo 802.11 pode liberar a lista atual de redes sem fio disponíveis antes que a verificação seja iniciada. Os aplicativos não devem assumir que chamar a função WlanScan adicionará à lista existente de redes sem fio disponíveis retornadas pelas funções WlanGetNetworkBssList ou WlanGetAvailableNetworkList de verificações anteriores.

A função WlanScan retorna imediatamente. Para ser notificado quando a verificação de rede for concluída, um cliente no Windows Vista e posterior deve se registrar para notificações chamando WlanRegisterNotification. O parâmetro dwNotifSource passado para a função WlanRegisterNotification deve ter o bit WLAN_NOTIFICATION_SOURCE_ACM definido para registrar notificações geradas pelo módulo de configuração automática. Drivers de rede sem fio que atendem aos requisitos do logotipo do Windows são necessários para concluir uma solicitação de função WlanScan em 4 segundos.

O Serviço de LAN Sem Fio não envia notificações quando as redes sem fio disponíveis são alteradas. O Serviço de LAN Sem Fio não controla as alterações na lista de redes disponíveis em várias verificações. O comportamento padrão atual é que o Serviço de LAN Sem Fio pede apenas ao driver de interface sem fio para verificar redes sem fio a cada 60 segundos e, em alguns casos (quando já conectado à rede sem fio), o Serviço de LAN Sem Fio não solicita verificações. A função WlanScan pode ser usada por um aplicativo para acompanhar as alterações de rede sem fio. O aplicativo deve primeiro se registrar para notificações de WLAN_NOTIFICATION_SOURCE_ACM. A função WlanScan pode ser chamada para iniciar uma verificação. Em seguida, o aplicativo deve aguardar para receber a notificação de wlan_notification_acm_scan_complete ou o tempo limite após 4 segundos. Em seguida, o aplicativo pode chamar a função WlanGetNetworkBssList ou WlanGetAvailableNetworkList para recuperar uma lista de redes sem fio disponíveis. Esse processo pode ser repetido periodicamente com o aplicativo acompanhando as alterações em redes sem fio disponíveis.

A função WlanScan retorna imediatamente e não fornece uma notificação quando a verificação é concluída no Windows XP com SP3 ou a API lan sem fio para Windows XP com SP2.

Como fica mais difícil para uma interface sem fio enviar e receber pacotes de dados enquanto uma verificação está ocorrendo, a função WlanScan pode aumentar a latência até que a verificação de rede seja concluída.

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