Função WlanHostedNetworkSetProperty (wlanapi.h)

Artigo
03/15/2023

A função WlanHostedNetworkSetProperty define propriedades estáticas da rede hospedada sem fio.

Sintaxe

DWORD WlanHostedNetworkSetProperty(
  [in]            HANDLE                      hClientHandle,
  [in]            WLAN_HOSTED_NETWORK_OPCODE  OpCode,
  [in]            DWORD                       dwDataSize,
  [in]            PVOID                       pvData,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  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 definida. Esse identificador só pode ser os seguintes valores na enumeração WLAN_HOSTED_NETWORK_OPCODE definida no arquivo de cabeçalho Wlanapi.h :

wlan_hosted_network_opcode_connection_settings

As configurações de conexão de Rede Hospedada.

wlan_hosted_network_opcode_enable

O sinalizador habilitado para Rede Hospedada.

[in] dwDataSize

Um valor que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pvData .

[in] pvData

Um ponteiro para um buffer com a propriedade estática a ser definida. O tipo de dados associado a esse buffer depende do valor do parâmetro OpCode .

[out, optional] pFailReason

Um ponteiro opcional para um valor que recebe o motivo da falha, se a chamada para a função WlanHostedNetworkSetProperty falhar. Os valores possíveis para o motivo da falha são do tipo de enumeração WLAN_HOSTED_NETWORK_REASON definido 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_ACCESS_DENIED	O chamador não tem permissões suficientes. Esse erro também será retornado se o parâmetro OpCode tiver sido wlan_hosted_network_opcode_enable e a rede hospedada sem fio estiver desabilitada pela política de grupo em um domínio.
ERROR_BAD_PROFILE	O perfil de conexão de rede usado pela Rede Hospedada sem fio está corrompido.
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. dwDataSize é zero. pvData é NULL. pvData não aponta para uma propriedade estática bem formada. 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_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se o aplicativo chamar a função WlanHostedNetworkSetProperty com o parâmetro OpCode definido como wlan_hosted_network_opcode_station_profile ou wlan_hosted_network_opcode_security_settings.
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 WlanHostedNetworkSetProperty é 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 WlanHostedNetworkSetProperty para definir as propriedades estáticas atuais da Rede Hospedada sem fio. Qualquer alteração de propriedade de Rede Hospedada causada por essa função não será desfeita automaticamente se o aplicativo de chamada fechar seu identificador de chamada (chamando WlanCloseHandle com o parâmetro hClientHandle ) ou se o processo terminar.

O tipo de dados associado ao buffer apontado pelo parâmetro pvData 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 é passado no parâmetro pvData .
wlan_hosted_network_opcode_enable	Um ponteiro para BOOL é passado no parâmetro pvData .

Se a função WlanHostedNetworkSetProperty for chamada com o parâmetro OpCode definido como wlan_hosted_network_opcode_enable, o usuário deverá ter o privilégio associado apropriado. As permissões são armazenadas em uma DACL (lista de controle de acesso discricionário) associada a um WLAN_SECURABLE_OBJECT. Para chamar a função WlanHostedNetworkSetProperty com o parâmetro OpCode de wlan_hosted_network_opcode_enable, o token de acesso do cliente do chamador deve ter privilégios elevados expostos pela seguinte enumeração no WLAN_SECURABLE_OBJECT:

wlan_secure_hosted_network_elevated_access

Se a função WlanHostedNetworkSetProperty for passada para qualquer um dos seguintes valores no parâmetro OpCode , a função falhará com ERROR_NOT_SUPPORTED:

wlan_hosted_network_opcode_station_profile
wlan_hosted_network_opcode_connection_settings

Para ter êxito, a função WlanHostedNetworkSetProperty deve persistir as novas configurações que exigem que o estado da Rede Hospedada seja transferido para wlan_hosted_network_idle se ele estivesse em execução no momento (wlan_hosted_network_active).

Qualquer usuário pode chamar essa função para definir as propriedades da Rede Hospedada. No entanto, para definir o sinalizador wlan_hosted_network_opcode_enable requer privilégios elevados. A capacidade de habilitar a Rede Hospedada sem fio também pode ser restrita pela política de grupo em um domínio.

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