Função WlanHostedNetworkSetSecondaryKey (wlanapi.h)

Artigo
08/28/2023

A função WlanHostedNetworkSetSecondaryKey configura a chave de segurança secundária que será usada pela rede hospedada sem fio.

Sintaxe

DWORD WlanHostedNetworkSetSecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [in]            DWORD                       dwKeyLength,
  [in]            PUCHAR                      pucKeyData,
  [in]            BOOL                        bIsPassPhrase,
  [in]            BOOL                        bPersistent,
  [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] dwKeyLength

O número de bytes de dados válidos na matriz de dados de chave apontada pelo parâmetro pucKeyData . Esse comprimento de chave deve incluir a terminação '\0' se a chave for uma frase secreta.

[in] pucKeyData

Um ponteiro para um buffer que contém os dados de chave. O número de bytes de dados válidos no buffer deve ser pelo menos o valor especificado no parâmetro dwKeyLength .

[in] bIsPassPhrase

Um valor booliano que indica se a matriz de dados de chave apontada pelo parâmetro pucKeyData 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.

[in] bPersistent

Um valor booliano que indica se a matriz de dados de chave apontada pelo parâmetro pucKeyData 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á usada para uma sessão (a sessão atual ou a próxima sessão se a Rede Hospedada não for iniciada).

[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 identificadores.
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se qualquer uma das seguintes condições ocorrer: hClientHandle é NULL. pucKeyData é NULL. pucKeyData não aponta para uma chave válida 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_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 WlanHostedNetworkSetSecondaryKey é 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 WlanHostedNetworkSetSecondaryKey para configurar a chave de segurança secundária que será usada pela Rede Hospedada sem fio. Qualquer alteração 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.

Uma vez iniciada, a Rede Hospedada sem fio permitirá que pares sem fio se associem a essa chave de segurança secundária, além da chave de segurança primária. A chave de segurança secundária é sempre especificada pelo usuário conforme necessário, enquanto a chave de segurança primária é gerada pelo sistema operacional com maior força de segurança.

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

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

Para configurar uma chave de segurança secundária válida, o parâmetro dwKeyLength deve estar no intervalo correto e o parâmetro pucKeyData deve apontar para um buffer de memória válido que contenha os bytes de dados especificados. Para remover a chave de segurança secundária atualmente configurada do sistema, o aplicativo deve chamar a função WlanHostedNetworkSetSecondaryKey com zero no parâmetro dwKeyLength e NULL no parâmetro pucKeyData .

A função WlanHostedNetworkSetSecondaryKey retornará ERROR_INVALID_PARAMETER se o parâmetro pucKeyData for NULL, mas o parâmetro dwKeyLength não for zero. A função WlanHostedNetworkSetSecondaryKey também retornará ERROR_INVALID_PARAMETER se o parâmetro dwKeyLength for zero, mas o parâmetro pucKeyData não for NULL.

A chave de segurança secundária geralmente é definida antes da rede hospedada sem fio ser iniciada. Em seguida, ele será usado na próxima vez em que a Rede Hospedada for iniciada.

Uma chave de segurança secundária também pode ser definida depois que a Rede Hospedada for iniciada. Nesse caso, a chave de segurança secundária será usada imediatamente. Todos os clientes que usam a chave de segurança secundária anterior permanecerão conectados, mas não poderão se reconectar se forem desconectados por qualquer motivo ou se a Rede Hospedada sem fio for reiniciada.

A chave de segurança secundária poderá ser especificada como persistente se o parâmetro bPersistent estiver definido como TRUE. Quando especificada como persistente, a chave de segurança secundária será usada imediatamente se a Rede Hospedada já estiver 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 pela próxima vez quando 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.

Qualquer usuário pode chamar essa função para configurar a chave de segurança secundária a ser 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 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