Função WlanHostedNetworkForceStart (wlanapi.h)

Artigo
08/28/2023

A função WlanHostedNetworkForceStart faz a transição da Rede Hospedada sem fio para o estado wlan_hosted_network_active sem associar a solicitação ao identificador de chamada do aplicativo.

Sintaxe

DWORD WlanHostedNetworkForceStart(
  [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 WlanHostedNetworkForceStart 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.

Valor retornado

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.
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. pvReserved não é NULL.
ERROR_INVALID_STATE	O recurso não está no estado correto para executar a operação solicitada. Esse erro será retornado se a Rede Hospedada sem fio estiver desabilitada pela política de grupo em um domínio.
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.
Outras	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 WlanHostedNetworkForceStart é 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 WlanHostedNetworkForceStart para forçar o início da rede hospedada sem fio fazendo a transição da Rede Hospedada sem fio para o estado wlan_hosted_network_active sem associar a solicitação ao identificador de chamada do aplicativo. Uma chamada bem-sucedida para a função WlanHostedNetworkForceStart deve eventualmente ser correspondida por uma chamada para a função WlanHostedNetworkForceStop . Qualquer alteração de estado 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 custo de chamar a função WlanHostedNetworkForceStart ao chamar WlanHostedNetworkStartUsing é o privilégio associado necessário. Um aplicativo pode chamar a função WlanHostedNetworkForceStart depois de garantir que um usuário do sistema com privilégios elevados aceite os requisitos de energia maiores envolvidos na execução da Rede Hospedada sem fio por longas durações.

A função WlanHostedNetworkForceStart poderá falhar se o estado da Rede Hospedada for wlan_hosted_network_unavailable ou se o chamador não tiver privilégios suficientes.

Essa função para forçar o início da Rede Hospedada só poderá ser chamada se o usuário tiver 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 o WlanHostedNetworkForceStart, 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

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 Conexões 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


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