Função WlanHostedNetworkQuerySecondaryKey (wlanapi.h)

Artigo
08/28/2023

A função WlanHostedNetworkQuerySecondaryKey consulta a chave de segurança secundária configurada para ser usada pela rede hospedada sem fio.

Sintaxe

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [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] pdwKeyLength

Um ponteiro para um valor que especifica o número de bytes de dados válidos na matriz de dados de chave apontada pelo parâmetro ppucKeyData , se a chamada para a função WlanHostedNetworkQuerySecondaryKey for bem-sucedida.

Esse comprimento de chave inclui a terminação '\0' se a chave for uma frase secreta.

[out] ppucKeyData

Um ponteiro para um valor que recebe um ponteiro para o buffer retornado com os dados da chave de segurança secundária, se a chamada para a função WlanHostedNetworkQuerySecondaryKey for bem-sucedida.

[out] pbIsPassPhrase

Um ponteiro para um valor booliano que indica se a matriz de dados de chave apontada pelo parâmetro ppucKeyData está no formato de frase secreta.

Se esse parâmetro for TRUE, a matriz de dados de chave estará no formato de frase secreta. Se esse parâmetro for FALSE, a matriz de dados de chave não estará no formato de frase secreta.

[out] pbPersistent

Um ponteiro para um valor booliano que indica se a matriz de dados de chave apontada pelo parâmetro ppucKeyData deve ser armazenada e reutilizado posteriormente ou é apenas para uso único.

Se esse parâmetro for TRUE, a matriz de dados de chave deverá ser armazenada e reutilizado posteriormente. Se esse parâmetro for FALSE, a matriz de dados de chave será somente para uso único.

[out, optional] pFailReason

Um ponteiro opcional para um valor que recebe o motivo da falha, se a chamada para a função WlanHostedNetworkSetSecondaryKey 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_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. pdwKeyLength é NULL. ppucKeyData é NULL ou inválido. pbIsPassPhrase é NULL ou inválido. pbPersistent é 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 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 WlanHostedNetworkQuerySecondaryKey é 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 WlanHostedNetworkQuerySecondaryKey para consultar a chave de segurança secundária que será usada pela rede hospedada sem fio. Essa função retornará as principais informações, incluindo dados de chave, comprimento da chave, se é uma frase secreta e se é persistente ou para uso único. Essa função não altera o estado ou as propriedades da Rede Hospedada sem fio.

A chave de segurança secundária será uma frase secreta se o valor apontado pelo parâmetro pbIsPassPhrase for TRUE. A chave de segurança secundária será uma chave binária se o valor apontado pelo parâmetro pbIsPassPhrase for FALSE.

A chave de segurança secundária retornada no buffer apontado pelo parâmetro ppucKeyData é usada com WPA2-Personal autenticação e está em um dos seguintes formatos:

Uma frase secreta que consiste em uma matriz de caracteres ASCII de 8 a 63 caracteres. O valor apontado pelo parâmetro pdwKeyLength inclui a terminação '\0' na frase secreta. O valor apontado pelo parâmetro pdwKeyLength deve estar no intervalo de 9 a 64.
Uma chave binária que consiste em 32 bytes de dados de chave binária. O valor apontado pelo parâmetro pdwKeyLength deve ser 32 para chave binária.

A chave de segurança secundária será persistente se o valor apontado pelo parâmetro pbPersistent for TRUE. Quando persistente, a chave de segurança secundária seria usada imediatamente se a Rede Hospedada já fosse iniciada e também reutilizado sempre que a Rede Hospedada for iniciada no futuro.

Se a chave de segurança secundária não for especificada como persistente, ela será usada imediatamente se a Rede Hospedada já estiver iniciada ou somente na próxima vez em que a Rede Hospedada for iniciada. Depois que a Rede Hospedada for interrompida, essa chave de segurança secundária nunca mais será usada e será removida do sistema.

Se não houver nenhuma chave de segurança secundária atualmente configurada, o valor retornado apontado pelo parâmetro pdwKeyLength será zero e o valor retornado no parâmetro ppucKeyData será NULL. Nesse caso, o valor retornado nos parâmetros pbIsPassPhrase e pbPersistent não terá sentido.

Se a função WlanHostedNetworkQuerySecondaryKey for bem-sucedida, a memória usada para o buffer no parâmetro ppucKeyData retornado deverá ser liberada após o uso chamando a função WlanFreeMemory .

Qualquer usuário pode chamar a função WlanHostedNetworkQuerySecondaryKey para consultar a chave de segurança secundária usada na Rede Hospedada. No entanto, a capacidade de habilitar a Rede Hospedada sem fio pode ser restrita pela política de grupo em um domínio.

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 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 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


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