Función WlanScan (wlanapi.h)

Artículo
03/04/2024

Nota

Parte de la información hace referencia al producto de versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.

Importante

Esta API se verá afectada por los próximos cambios en el comportamiento del sistema operativo, previsto para el otoño de 2024. Para obtener más información, consulte Cambios en el comportamiento de la API para Wi-Fi acceso y ubicación.

La función WlanScan solicita un examen de las redes disponibles en la interfaz indicada.

Sintaxis

DWORD WlanScan(
  [in]           HANDLE               hClientHandle,
  [in]           const GUID           *pInterfaceGuid,
  [in, optional] const PDOT11_SSID    pDot11Ssid,
  [in, optional] const PWLAN_RAW_DATA pIeData,
                 PVOID                pReserved
);

Parámetros

[in] hClientHandle

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

[in] pInterfaceGuid

GUID de la interfaz que se va a consultar.

El GUID de cada interfaz LAN inalámbrica habilitada en un equipo local se puede determinar mediante la función WlanEnumInterfaces .

[in, optional] pDot11Ssid

Puntero a una estructura DOT11_SSID que especifica el SSID de la red que se va a examinar. Este parámetro es opcional. Cuando se establece en NULL, la lista devuelta contiene todas las redes disponibles. Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Este parámetro debe ser NULL.

[in, optional] pIeData

Puntero a un elemento de información que se va a incluir en las solicitudes de sondeo. Este parámetro apunta a una estructura de WLAN_RAW_DATA que puede incluir información de disponibilidad de aprovisionamiento de cliente y requisitos de autenticación 802.1X. Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Este parámetro debe ser NULL.

pReserved

Reservado para uso futuro. Debe establecerse en 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_PARAMETER	hClientHandle es NULL o no es válido, pInterfaceGuid es NULL o pReserved no es NULL.
ERROR_INVALID_HANDLE	No se encontró el identificador hClientHandle en la tabla handle.
RPC_STATUS	Varios códigos de error.
ERROR_NOT_ENOUGH_MEMORY	No se pudo asignar memoria para los resultados de la consulta.

Comentarios

La función WlanScan solicita que el controlador laN inalámbrico 802.11 nativo busque redes inalámbricas disponibles. El controlador puede o no enviar solicitudes de sondeo (un examen activo) según su implementación y los valores pasados en los parámetros pDot11Ssid y pIeData .

Si el parámetro pIeData no es NULL, el controlador enviará solicitudes de sondeo durante el examen. Las solicitudes de sondeo incluyen el elemento de información (IE) al que apunta el parámetro pIeData . Por ejemplo, el Wi-Fi IE de configuración protegida (WPS) se puede incluir en las solicitudes de sondeo para detectar puntos de acceso compatibles con WPS. El búfer al que apunta el parámetro pIeData debe contener el IE completo a partir del identificador de elemento.

El parámetro pIeData pasado a la función WlanScan puede contener un puntero a una estructura opcional WLAN_RAW_DATA que contiene una entrada de datos IE de detección de servicios de proximidad (PSD).

Cuando se usa para almacenar un IE de PSD, la constante DOT11_PSD_IE_MAX_DATA_SIZE definida en el archivo de encabezado Wlanapi.h es el valor máximo del miembro dwDataSize .

Constante	Valor	Descripción
DOT11_PSD_IE_MAX_DATA_SIZE	240	Tamaño máximo de datos, en bytes, de una entrada de datos de PSD IE.

Para obtener más información sobre las IE de PSD, incluida una explicación del formato de un IE de PSD, consulta la función WlanSetPsdIEDataList .

Cuando se llama a la función WlanScan , el controlador LAN inalámbrico nativo 802.11 puede vaciar la lista actual de redes inalámbricas disponibles antes de que se inicie el examen. Las aplicaciones no deben suponer que al llamar a la función WlanScan se agregará a la lista existente de redes inalámbricas disponibles devueltas por las funciones WlanGetNetworkBssList o WlanGetAvailableNetworkList de exámenes anteriores.

La función WlanScan devuelve inmediatamente. Para recibir notificaciones cuando se complete el examen de red, un cliente de Windows Vista y versiones posteriores debe registrarse para recibir notificaciones mediante una llamada a WlanRegisterNotification. El parámetro dwNotifSource pasado a la función WlanRegisterNotification debe tener el bit de WLAN_NOTIFICATION_SOURCE_ACM establecido para registrarse para las notificaciones generadas por el módulo de configuración automática. Los controladores de red inalámbrica que cumplen los requisitos del logotipo de Windows son necesarios para completar una solicitud de función WlanScan en 4 segundos.

El servicio LAN inalámbrico no envía notificaciones cuando cambian las redes inalámbricas disponibles. El servicio LAN inalámbrico no realiza un seguimiento de los cambios en la lista de redes disponibles en varios exámenes. El comportamiento predeterminado actual es que el servicio LAN inalámbrico solo pide al controlador de la interfaz inalámbrica que busque redes inalámbricas cada 60 segundos, y en algunos casos (cuando ya está conectado a la red inalámbrica), el servicio LAN inalámbrico no solicita exámenes en absoluto. La función WlanScan puede ser utilizada por una aplicación para realizar un seguimiento de los cambios de red inalámbrica. La aplicación debe registrarse primero para WLAN_NOTIFICATION_SOURCE_ACM notificaciones. A continuación, se puede llamar a la función WlanScan para iniciar un examen. A continuación, la aplicación debe esperar a recibir la notificación de wlan_notification_acm_scan_complete o el tiempo de espera después de 4 segundos. A continuación, la aplicación puede llamar a la función WlanGetNetworkBssList o WlanGetAvailableNetworkList para recuperar una lista de redes inalámbricas disponibles. Este proceso se puede repetir periódicamente con la aplicación realizando un seguimiento de los cambios en las redes inalámbricas disponibles.

La función WlanScan devuelve inmediatamente y no proporciona una notificación cuando el examen se completa en Windows XP con SP3 o la API de LAN inalámbrica para Windows XP con SP2.

Puesto que resulta más difícil que una interfaz inalámbrica envíe y reciba paquetes de datos mientras se produce un examen, la función WlanScan puede aumentar la latencia hasta que se complete el examen de red.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista, Windows XP con SP3 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wlanapi.h (incluya Wlanapi.h)
Library	Wlanapi.lib
Archivo DLL	Wlanapi.dll
Redistribuible	API de LAN inalámbrica para Windows XP con SP2