Função WlanHostedNetworkQueryProperty (wlanapi.h)

Artigo
03/04/2024

A função WlanHostedNetworkQueryProperty consulta as propriedades estáticas atuais da rede hospedada sem fio.

Sintaxe

DWORD WlanHostedNetworkQueryProperty(
  [in]  HANDLE                     hClientHandle,
  [in]  WLAN_HOSTED_NETWORK_OPCODE OpCode,
  [out] PDWORD                     pdwDataSize,
  [out] PVOID                      *ppvData,
  [out] PWLAN_OPCODE_VALUE_TYPE    pWlanOpcodeValueType,
        PVOID                      pvReserved
);

Parâmetros

[in] hClientHandle

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

[in] OpCode

O identificador da propriedade a ser consultada. Esse identificador pode ser qualquer um dos valores na enumeração WLAN_HOSTED_NETWORK_OPCODE definida no arquivo de cabeçalho Wlanapi.h .

[out] pdwDataSize

Um ponteiro para um valor que especifica o tamanho, em bytes, do buffer retornado no parâmetro ppvData , se a chamada para a função WlanHostedNetworkQueryProperty for bem-sucedida.

[out] ppvData

Na entrada, esse parâmetro deve ser NULL.

Na saída, esse parâmetro receberá um ponteiro para um buffer retornado com a propriedade estática solicitada, se a chamada para a função WlanHostedNetworkQueryProperty for bem-sucedida. O tipo de dados associado a esse buffer depende do valor do parâmetro OpCode .

[out] pWlanOpcodeValueType

Um ponteiro para um valor que recebe o tipo de valor da propriedade rede hospedada sem fio, se a chamada para a função WlanHostedNetworkQueryProperty for bem-sucedida. O valor retornado é um tipo enumerado na enumeração WLAN_OPCODE_VALUE_TYPE definida no arquivo de cabeçalho Wlanapi.h .

pvReserved

Reservado para uso futuro. Esse parâmetro deve ser 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_BAD_CONFIGURATION	Os dados de configuração da Rede Hospedada sem fio não estão configurados. Esse erro será retornado se o aplicativo chamar a função WlanHostedNetworkQueryProperty com o parâmetro OpCode definido como wlan_hosted_network_opcode_station_profile ou wlan_hosted_network_opcode_connection_settings antes que um SSID seja configurado na Rede Hospedada sem fio.
ERROR_INVALID_HANDLE	Um identificador é inválido. Esse erro será retornado se o identificador especificado no parâmetro hClientHandle não tiver sido encontrado na tabela de identificadores.
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se qualquer uma das seguintes condições ocorrer: hClientHandle é NULL. OpCode não é um dos valores enumerados definidos no WLAN_HOSTED_NETWORK_OPCODE. pdwDataSize é NULL. ppvData é NULL. pWlanOpcodeValueType é NULL. pvReserved não é NULL.
ERROR_INVALID_STATE	O recurso não está no estado correto para executar a operação solicitada. Isso pode ocorrer se a Rede Hospedada sem fio estiver em processo de desligamento.
ERROR_OUTOFMEMORY	Não há armazenamento suficiente disponível para concluir esta operação.
ERROR_SERVICE_NOT_ACTIVE	O serviço não foi iniciado. Esse erro será retornado se o Serviço de Configuração Automática da WLAN não estiver em execução.
Outros	Vários RPC e outros códigos de erro. Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função WlanHostedNetworkQueryProperty é uma extensão para APIs sem fio nativas adicionadas para dar suporte à Rede Hospedada sem fio no Windows 7 e no Windows Server 2008 R2 com o Serviço lan sem fio instalado.

Um aplicativo cliente chama a função WlanHostedNetworkQueryProperty para consultar as propriedades estáticas atuais da rede hospedada sem fio. Essa função não altera o estado ou as propriedades da Rede Hospedada sem fio.

Se a função for bem-sucedida, o parâmetro ppvData apontará para um buffer que contém a propriedade solicitada. O tamanho desse buffer é retornado em um ponteiro retornado no parâmetro pwdDataSize . O WLAN_OPCODE_VALUE_TYPE é retornado em um ponteiro retornado no parâmetro pWlanOpcodeValueType . A memória usada para o buffer no parâmetro ppvData retornado deve ser liberada chamando a função WlanFreeMemory depois que o buffer não for mais necessário.

O tipo de dados associado ao buffer apontado pelo parâmetro ppvData depende do valor do parâmetro OpCode da seguinte maneira:

OpCode	Descrição
wlan_hosted_network_opcode_connection_settings	Um ponteiro para uma estrutura WLAN_HOSTED_NETWORK_CONNECTION_SETTINGS é retornado.
wlan_hosted_network_opcode_security_settings	Um ponteiro para uma estrutura WLAN_HOSTED_NETWORK_SECURITY_SETTINGS é retornado.
wlan_hosted_network_opcode_station_profile	Um PWSTR para conter um perfil WLAN XML para se conectar à Rede Hospedada sem fio é retornado.
wlan_hosted_network_opcode_enable	Um PBOOL que indica se a Rede Hospedada sem fio está habilitada é retornada.

Se a função WlanHostedNetworkQueryProperty for passada para qualquer um dos seguintes valores no parâmetro OpCode antes que um SSID seja configurado na Rede Hospedada sem fio, a função falhará com ERROR_BAD_CONFIGURATION:

wlan_hosted_network_opcode_station_profile
wlan_hosted_network_opcode_connection_settings

Qualquer usuário pode chamar a função WlanHostedNetworkQueryProperty para consultar as propriedades da Rede Hospedada.

No Windows 7 e posterior, o sistema operacional instalará um dispositivo virtual se um adaptador sem fio compatível com a Rede Hospedada estiver presente no computador. Esse dispositivo virtual normalmente aparece na "Pasta de Connections de Rede" como "Conexão de Rede Sem Fio 2" com um Nome de Dispositivo de "Adaptador de Miniporto WiFi Virtual da Microsoft" se o computador tiver um único adaptador de rede sem fio. Esse dispositivo virtual é usado exclusivamente para executar conexões de ponto de acesso de software (SoftAP) e não está presente na lista retornada pela função WlanEnumInterfaces . O tempo de vida desse dispositivo virtual está vinculado ao adaptador sem fio físico. Se o adaptador físico sem fio estiver desabilitado, esse dispositivo virtual também será removido. Esse recurso também está disponível no Windows Server 2008 R2 com o Serviço lan sem fio instalado.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wlanapi.h (inclua Wlanapi.h)
Biblioteca	Wlanapi.lib
DLL	Wlanapi.dll