Função WlanHostedNetworkInitSettings (wlanapi.h)

Artigo
08/28/2023

A função WlanHostedNetworkInitSettings configura e persiste para armazenar as configurações de conexão de rede (SSID e o número máximo de pares, por exemplo) na Rede Hospedada sem fio se essas configurações ainda não estiverem configuradas.

Sintaxe

DWORD WlanHostedNetworkInitSettings(
  [in]            HANDLE                      hClientHandle,
  [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 .

[out, optional] pFailReason

Um ponteiro opcional para um valor que recebe o motivo da falha se a chamada para a função WlanHostedNetworkInitSettings 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_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 identificador.
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se alguma das seguintes condições ocorrer: hClientHandle é NULL. pvReserved não é NULL.
ERROR_INVALID_STATE	O recurso não está no estado correto para executar a operação solicitada.
ERROR_SERVICE_NOT_ACTIVE	O serviço não foi iniciado. Esse erro será retornado se o Serviço de Configuração Automática 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 WlanHostedNetworkInitSettings é 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 de LAN Sem Fio instalado.

Um aplicativo cliente chama a função WlanHostedNetworkInitSettings para definir e persistir para armazenar as configurações de conexão de rede (SSID e o número máximo de pares, por exemplo) na Rede Hospedada sem fio, se as configurações de conexões ainda não estiverem definidas. Se as configurações de rede nas configurações de Rede Hospedada sem fio já estiverem definidas (a função WlanHostedNetworkQueryProperty não retornará ERROR_BAD_CONFIGURATION para o perfil da estação ou as configurações de conexão), essa chamada de função retornará ERROR_SUCCESS sem alterar a configuração das configurações de conexão de rede.

Um aplicativo cliente sempre deve chamar a função WlanHostedNetworkInitSettings antes de usar outros recursos da Rede Hospedada no computador local. Essa função inicializa as configurações necessárias quando a rede hospedada sem fio é usada pela primeira vez em um computador local. A função WlanHostedNetworkInitSettings não alterará nenhuma configuração se a configuração já tiver sido persistente. Portanto, é seguro chamar a função WlanHostedNetworkInitSettings se a configuração já tiver sido persistente. É recomendável que os aplicativos que usam a Rede Hospedada chamem a função WlanHostedNetworkInitSettings antes de usar outras funções de Rede Hospedada.

A função WlanHostedNetworkInitSettings calcula um SSID aleatório e legível do nome do host e calcula uma chave primária aleatória. Essa função também usa conjuntos de um valor para o número máximo de pares permitidos que o padrão é 100. Se um aplicativo quiser usar um SSID diferente ou um número máximo diferente de pares, o aplicativo deverá chamar a função WlanHostedNetworkSetProperty para definir especificamente essas propriedades usadas pela rede hospedada sem fio.

Qualquer alteração de estado de Rede Hospedada causada por essa função não seria desfeita automaticamente se o aplicativo de chamada fechasse seu identificador de chamada (chamando WlanCloseHandle com o parâmetro hClientHandle ) ou se o processo terminasse.

Qualquer usuário pode chamar a função WlanHostedNetworkInitSettings para definir e persistir nas configurações de conexão de rede de armazenamento na Rede Hospedada. Se a rede hospedada sem fio já tiver sido configurada, essa função não fará nada e retornará ERROR_SUCCESS.

No Windows 7 e posteriores, 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 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 sem fio físico 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 de 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