Função WlanGetNetworkBssList (wlanapi.h)

Artigo
10/19/2023

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 WlanGetNetworkBssList recupera uma lista das entradas básicas do BSS (conjunto de serviços) da rede sem fio ou redes em uma determinada interface lan sem fio.

Sintaxe

DWORD WlanGetNetworkBssList(
  [in]       HANDLE            hClientHandle,
  [in]       const GUID        *pInterfaceGuid,
  [optional] const PDOT11_SSID pDot11Ssid,
  [in]       DOT11_BSS_TYPE    dot11BssType,
  [in]       BOOL              bSecurityEnabled,
             PVOID             pReserved,
  [out]      PWLAN_BSS_LIST    *ppWlanBssList
);

Parâmetros

[in] hClientHandle

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

[in] pInterfaceGuid

Um ponteiro para o GUID da interface lan sem fio a ser consultada.

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

[optional] pDot11Ssid

Um ponteiro para uma estrutura DOT11_SSID que especifica o SSID da rede da qual a lista BSS é solicitada. Esse parâmetro é opcional. Quando definida como NULL, a lista retornada contém todas as entradas BSS disponíveis em uma interface LAN sem fio.

Se um ponteiro para uma estrutura DOT11_SSID for especificado, o comprimento SSID especificado no membro uSSIDLength de DOT11_SSID estrutura deverá ser menor ou igual a DOT11_SSID_MAX_LENGTH definido no arquivo de cabeçalho Wlantypes.h . Além disso, o parâmetro dot11BssType deve ser definido como dot11_BSS_type_infrastructure ou dot11_BSS_type_independent e o parâmetro bSecurityEnabled deve ser especificado.

[in] dot11BssType

O tipo BSS da rede. Esse parâmetro será ignorado se o SSID da rede da lista BSS não for especificado (o parâmetro pDot11Ssid for NULL).

Esse parâmetro pode ser um dos seguintes valores definidos na enumeração DOT11_BSS_TYPE definida no arquivo de cabeçalho Wlantypes.h .

Valor	Significado
dot11_BSS_type_infrastructure	Uma rede BSS de infraestrutura.
dot11_BSS_type_independent	Uma rede independente do BSS (IBSS) (uma rede ad hoc).
dot11_BSS_type_any	Qualquer rede BSS.

[in] bSecurityEnabled

Um valor que indica se a segurança está habilitada na rede. Esse parâmetro só é válido quando o SSID da rede para a lista BSS é especificado (o parâmetro pDot11Ssid não é NULL).

pReserved

Reservado para uso futuro. Esse parâmetro deve ser definido como NULL.

[out] ppWlanBssList

Um ponteiro para o armazenamento de um ponteiro para receber a lista retornada de entradas BSS em uma estrutura WLAN_BSS_LIST .

O buffer para o WLAN_BSS_LIST retornado será alocado pela função WlanGetNetworkBssList se a chamada for bem-sucedida.

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_HANDLE	O identificador hClientHandle não foi encontrado na tabela de identificadores.
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se o parâmetro hClientHandle, pInterfaceGuid ou ppWlanBssList for NULL. Esse erro será retornado se o pReserved não for NULL. Esse erro também será retornado se o hClientHandle, o SSID especificado no parâmetro pDot11Ssid ou o tipo BSS especificado no parâmetro dot11BssType não for válido.
ERROR_NDIS_DOT11_POWER_STATE_INVALID	O rádio associado à interface está desativado. A lista BSS não está disponível quando o rádio está desativado.
ERROR_NOT_ENOUGH_MEMORY	Não há memória suficiente disponível para processar essa solicitação e alocar memória para os resultados da consulta.
ERROR_NOT_FOUND	O elemento não foi encontrado. Esse erro será retornado se o GUID da interface a ser consultada que foi especificado no parâmetro pInterfaceGuid não puder ser encontrado.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se essa função tiver sido chamada de um Windows XP com SP3 ou API lan sem fio para Windows XP com cliente SP2. Esse erro também será retornado se o serviço de Configuração Automática da WLAN estiver desabilitado.
ERROR_SERVICE_NOT_ACTIVE	O serviço de Configuração Automática da WLAN não foi iniciado.
RPC_STATUS	Vários códigos de erro.

Comentários

A função WlanGetNetworkBssList recupera a lista básica de conjuntos de serviços para cada rede sem fio ou redes acessíveis em uma determinada interface. A lista de informações retornadas para cada rede sem fio também contém uma lista de elementos de informações retornados por cada ponto de acesso para uma rede BSS de infraestrutura ou um par de rede para uma rede BSS independente (rede ad hoc). As informações são retornadas como um ponteiro para uma estrutura WLAN_BSS_LIST no parâmetro ppWlanBssList . A estrutura WLAN_BSS_LIST contém uma contagem de itens seguida por uma matriz de entradas de estrutura WLAN_BSS_ENTRY .

Como as informações retornadas pela função WlanGetNetworkBssList são enviadas por um ponto de acesso para uma rede BSS de infraestrutura ou por um par de rede para uma rede BSS independente (rede ad hoc), as informações retornadas não devem ser confiáveis. Os membros ulIeOffset e ulIeSize na estrutura WLAN_BSS_ENTRY devem ser usados para determinar o tamanho do blob de dados do elemento de informações na estrutura WLAN_BSS_ENTRY , não os dados no próprio blob de dados do elemento de informações. A função WlanGetNetworkBssList não valida se nenhuma informação retornada no blob de dados do elemento de informações apontado pelo membro ulIeOffset é um elemento de informações válido, conforme definido pelos padrões IEEE 802.11 para LANs sem fio.

Se o parâmetro pDot11Ssid for especificado (não NULL), o parâmetro dot11BssType especificado deverá ser definido como dot11_BSS_type_infrastructure para uma rede BSS de infraestrutura ou dot11_BSS_type_independent para uma rede BSS independente (rede ad hoc). Se o parâmetro dot11BssType for definido como dot11_BSS_type_any, a função WlanGetNetworkBssList retornará ERROR_SUCCESS mas nenhuma entrada BSS será retornada.

Para retornar uma lista de todas as redes BSS de infraestrutura e redes BSS independentes (redes ad hoc) em uma interface lan sem fio, defina o parâmetro pDot11Ssid como NULL. Quando a interface lan sem fio também estiver operando como uma rede hospedada sem fio, a lista BSS conterá uma entrada para o BSS criado para a rede hospedada sem fio.

A função WlanGetNetworkBssList retorna ERROR_SUCCESS quando uma lista BSS vazia é retornada pelo Serviço de Configuração Automática da WLAN. Um aplicativo que chama a função WlanGetNetworkBssList deve marcar que o membro dwNumberOfItems do WLAN_BSS_LIST apontado pelo parâmetro ppWlanBssList não seja zero antes de acessar o membro wlanBssEntries[0] na estrutura WLAN_BSS_LIST.

A função WlanGetNetworkBssList aloca memória para a lista de conjuntos de serviços básico que é retornada em um buffer apontado pelo parâmetro ppWlanBssList quando a função é bem-sucedida. A memória usada para o buffer apontado pelo parâmetro ppWlanBssList deve ser liberada chamando a função WlanFreeMemory depois que o buffer não for mais necessário.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [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