Función WlanHostedNetworkQuerySecondaryKey (wlanapi.h)

Artículo
03/15/2023

La función WlanHostedNetworkQuerySecondaryKey consulta la clave de seguridad secundaria configurada para ser utilizada por la red hospedada inalámbrica.

Sintaxis

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

Identificador de sesión del cliente, devuelto por una llamada anterior a la función WlanOpenHandle .

[out] pdwKeyLength

Puntero a un valor que especifica el número de bytes de datos válidos en la matriz de datos clave a la que apunta el parámetro ppucKeyData , si la llamada a la función WlanHostedNetworkQuerySecondaryKey se realiza correctamente.

Esta longitud de clave incluye la terminación '\0' si la clave es una frase de contraseña.

[out] ppucKeyData

Puntero a un valor que recibe un puntero al búfer devuelto con los datos de la clave de seguridad secundaria, si la llamada a la función WlanHostedNetworkQuerySecondaryKey se realiza correctamente.

[out] pbIsPassPhrase

Puntero a un valor booleano que indica si la matriz de datos de clave a la que apunta el parámetro ppucKeyData está en formato de frase de contraseña.

Si este parámetro es TRUE, la matriz de datos de clave está en formato de frase de contraseña. Si este parámetro es FALSE, la matriz de datos de clave no está en formato de frase de contraseña.

[out] pbPersistent

Puntero a un valor booleano que indica si la matriz de datos de clave a la que apunta el parámetro ppucKeyData se va a almacenar y reutilizar más adelante o es solo para uso único.

Si este parámetro es TRUE, la matriz de datos de clave se almacenará y reutilizará más adelante. Si este parámetro es FALSE, la matriz de datos de clave es solo para uso único.

[out, optional] pFailReason

Puntero opcional a un valor que recibe el motivo del error, si se produce un error en la llamada a la función WlanHostedNetworkSetSecondaryKey . Los valores posibles por el motivo del error proceden del tipo de enumeración WLAN_HOSTED_NETWORK_REASON definido en el archivo de encabezado Wlanapi.h .

pvReserved

Reservado para uso futuro. Este parámetro debe ser NULL.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de retorno.

Código devuelto	Descripción
ERROR_INVALID_HANDLE	Un identificador no es válido. Este error se devuelve si no se encontró el identificador especificado en el parámetro hClientHandle en la tabla de identificadores.
ERROR_INVALID_PARAMETER	Un parámetro es incorrecto. Este error se devuelve si se produce alguna de las condiciones siguientes: hClientHandle es NULL. pdwKeyLength es NULL. ppucKeyData es NULL o no es válido. pbIsPassPhrase es NULL o no es válido. pbPersistent es NULL. pvReserved no es NULL.
ERROR_INVALID_STATE	El recurso no está en el estado correcto para realizar la operación solicitada. Esto puede ocurrir si la red hospedada inalámbrica estaba en proceso de apagado.
ERROR_OUTOFMEMORY	No hay suficiente almacenamiento disponible para completar esta operación.
ERROR_SERVICE_NOT_ACTIVE	El servicio no se ha iniciado. Este error se devuelve si el servicio WLAN AutoConfig no se está ejecutando.
Otros	Varios rpc y otros códigos de error. Use FormatMessage para obtener la cadena de mensaje del error devuelto.

Observaciones

La función WlanHostedNetworkQuerySecondaryKey es una extensión de las API inalámbricas nativas agregadas para admitir la red inalámbrica hospedada en Windows 7 y en Windows Server 2008 R2 con el servicio LAN inalámbrico instalado.

Una aplicación cliente llama a la función WlanHostedNetworkQuerySecondaryKey para consultar la clave de seguridad secundaria que usará la red hospedada inalámbrica. Esta función devolverá la información clave, incluidos los datos clave, la longitud de la clave, si es una frase de contraseña y si es persistente o para un uso único. Esta función no cambia el estado ni las propiedades de la red hospedada inalámbrica.

La clave de seguridad secundaria es una frase de contraseña si el valor al que apunta el parámetro pbIsPassPhrase es TRUE. La clave de seguridad secundaria es una clave binaria si el valor al que apunta el parámetro pbIsPassPhrase es FALSE.

La clave de seguridad secundaria devuelta en el búfer a la que apunta el parámetro ppucKeyData se usa con WPA2-Personal autenticación y tiene uno de los siguientes formatos:

Frase de contraseña de clave que consta de una matriz de caracteres ASCII de 8 a 63 caracteres. El valor al que apunta el parámetro pdwKeyLength incluye la terminación '\0' en la frase de contraseña. El valor al que apunta el parámetro pdwKeyLength debe estar en el intervalo de 9 a 64.
Clave binaria que consta de 32 bytes de datos de clave binaria. El valor al que apunta el parámetro pdwKeyLength debe ser 32 para la clave binaria.

La clave de seguridad secundaria es persistente si el valor al que apunta el parámetro pbPersistent es TRUE. Cuando es persistente, la clave de seguridad secundaria se usaría inmediatamente si la red hospedada ya está iniciada y también se reutiliza siempre que se inicie la red hospedada en el futuro.

Si la clave de seguridad secundaria no se especifica como persistente, se usará inmediatamente si la red hospedada ya se ha iniciado o solo para la próxima vez que se inicie la red hospedada. Una vez detenida la red hospedada, esta clave de seguridad secundaria nunca se usará de nuevo y se quitará del sistema.

Si no hay ninguna clave de seguridad secundaria configurada actualmente, el valor devuelto al que apunta el parámetro pdwKeyLength será cero y el valor devuelto en el parámetro ppucKeyData será NULL. En tal caso, el valor devuelto en los parámetros pbIsPassPhrase y pbPersistent no tendrá sentido.

Si la función WlanHostedNetworkQuerySecondaryKey se realiza correctamente, la memoria utilizada para el búfer en el parámetro ppucKeyData que se devuelve debe liberarse después de su uso llamando a la función WlanFreeMemory .

Cualquier usuario puede llamar a la función WlanHostedNetworkQuerySecondaryKey para consultar la clave de seguridad secundaria usada en la red hospedada. Sin embargo, la capacidad de habilitar la red hospedada inalámbrica puede estar restringida por la directiva de grupo en un dominio.

En Windows 7 y versiones posteriores, el sistema operativo instala un dispositivo virtual si un adaptador inalámbrico compatible con red hospedada está presente en la máquina. Este dispositivo virtual normalmente aparece en la "Carpeta de conexiones de red" como "Conexión de red inalámbrica 2" con un nombre de dispositivo de "Adaptador de miniporte de Microsoft Virtual WiFi" si el equipo tiene un único adaptador de red inalámbrica. Este dispositivo virtual se usa exclusivamente para realizar conexiones de punto de acceso de software (SoftAP) y no está presente en la lista devuelta por la función WlanEnumInterfaces . La duración de este dispositivo virtual está vinculada al adaptador inalámbrico físico. Si el adaptador inalámbrico físico está deshabilitado, este dispositivo virtual también se quitará. Esta característica también está disponible en Windows Server 2008 R2 con el servicio LAN inalámbrico instalado.

Requisitos


Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wlanapi.h (incluya Wlanapi.h)
Library	Wlanapi.lib
Archivo DLL	Wlanapi.dll