Función WlanGetNetworkBssList (wlanapi.h)
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 WlanGetNetworkBssList recupera una lista de las entradas básicas del conjunto de servicios (BSS) de la red inalámbrica o redes en una interfaz LAN inalámbrica determinada.
Sintaxis
DWORD WlanGetNetworkBssList(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[optional] const PDOT11_SSID pDot11Ssid,
[in] DOT11_BSS_TYPE dot11BssType,
[in] BOOL bSecurityEnabled,
PVOID pReserved,
[out] PWLAN_BSS_LIST *ppWlanBssList
);
Parámetros
[in] hClientHandle
Identificador de sesión del cliente, obtenido por una llamada anterior a la función WlanOpenHandle .
[in] pInterfaceGuid
Puntero al GUID de la interfaz LAN inalámbrica 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 .
[optional] pDot11Ssid
Puntero a una estructura de DOT11_SSID que especifica el SSID de la red desde la que se solicita la lista de BSS. Este parámetro es opcional. Cuando se establece en NULL, la lista devuelta contiene todas las entradas BSS disponibles en una interfaz LAN inalámbrica.
Si se especifica un puntero a una estructura de DOT11_SSID , la longitud de SSID especificada en el miembro uSSIDLength de DOT11_SSID estructura debe ser menor o igual que DOT11_SSID_MAX_LENGTH definida en el archivo de encabezado Wlantypes.h . Además, el parámetro dot11BssType debe establecerse en dot11_BSS_type_infrastructure o dot11_BSS_type_independent y se debe especificar el parámetro bSecurityEnabled .
[in] dot11BssType
El tipo BSS de la red. Este parámetro se omite si el SSID de la red de la lista BSS no está especificado (el parámetro pDot11Ssid es NULL).
Este parámetro puede ser uno de los siguientes valores definidos en la enumeración DOT11_BSS_TYPE definida en el archivo de encabezado Wlantypes.h .
| Valor | Significado |
|---|---|
|
Una red BSS de infraestructura. |
|
Una red BSS (IBSS) independiente (una red ad hoc). |
|
Cualquier red BSS. |
[in] bSecurityEnabled
Valor que indica si la seguridad está habilitada en la red. Este parámetro solo es válido cuando se especifica el SSID de la red para la lista BSS (el parámetro pDot11Ssid no es NULL).
pReserved
Reservado para uso futuro. Este parámetro debe establecerse en NULL.
[out] ppWlanBssList
Puntero al almacenamiento de un puntero para recibir la lista de entradas de BSS devueltas en una estructura de WLAN_BSS_LIST .
La función WlanGetNetworkBssList asigna el búfer del WLAN_BSS_LIST devuelto si la llamada se realiza correctamente.
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 |
|---|---|
|
No se encontró el identificador hClientHandle en la tabla handle. |
|
Un parámetro es incorrecto. Este error se devuelve si el parámetro hClientHandle, pInterfaceGuid o ppWlanBssList es NULL. Este error se devuelve si pReserved no es NULL. Este error también se devuelve si hClientHandle, el SSID especificado en el parámetro pDot11Ssid o el tipo BSS especificado en el parámetro dot11BssType no es válido. |
|
La radio asociada a la interfaz está desactivada. La lista BSS no está disponible cuando la radio está desactivada. |
|
No hay suficiente memoria disponible para procesar esta solicitud y asignar memoria para los resultados de la consulta. |
|
No se encontró el elemento. Este error se devuelve si no se encontró el GUID de la interfaz que se va a consultar que se especificó en el parámetro pInterfaceGuid . |
|
No se admite la solicitud. Este error se devuelve si se llamó a esta función desde un Windows XP con SP3 o LAN inalámbrica API para Windows XP con el cliente SP2. Este error también se devuelve si el servicio WLAN AutoConfig está deshabilitado. |
|
No se ha iniciado el servicio WLAN AutoConfig. |
|
Varios códigos de error. |
Comentarios
La función WlanGetNetworkBssList recupera la lista básica de conjuntos de servicios para cada red inalámbrica o redes accesibles en una interfaz determinada. La lista de información devuelta para cada red inalámbrica también contiene una lista de elementos de información devueltos por cada punto de acceso para una red BSS de infraestructura o un par de red para una red BSS independiente (red ad hoc). La información se devuelve como puntero a una estructura de WLAN_BSS_LIST en el parámetro ppWlanBssList . La estructura WLAN_BSS_LIST contiene un recuento de elementos seguido de una matriz de entradas de estructura WLAN_BSS_ENTRY .
Dado que la información devuelta por la función WlanGetNetworkBssList es enviada por un punto de acceso para una red BSS de infraestructura o por un par de red para una red BSS independiente (red ad hoc), la información devuelta no debe ser de confianza. Los miembros ulIeOffset y ulIeSize de la estructura WLAN_BSS_ENTRY deben usarse para determinar el tamaño del blob de datos del elemento de información en la estructura WLAN_BSS_ENTRY , no los datos del propio blob de datos del elemento de información. La función WlanGetNetworkBssList no valida que ninguna información devuelta en el blob de datos del elemento de información al que apunta el miembro ulIeOffset es un elemento de información válido según lo definido por los estándares IEEE 802.11 para LASN inalámbricas.
Si se especifica el parámetro pDot11Ssid (no NULL), el parámetro dot11BssType especificado debe establecerse en dot11_BSS_type_infrastructure para una red BSS de infraestructura o dot11_BSS_type_independent para una red BSS independiente (red ad hoc). Si el parámetro dot11BssType se establece en dot11_BSS_type_any, la función WlanGetNetworkBssList devuelve ERROR_SUCCESS pero no se devolverán entradas BSS.
Para devolver una lista de todas las redes BSS de infraestructura y redes BSS independientes (redes ad hoc) en una interfaz LAN inalámbrica, establezca el parámetro pDot11Ssid en NULL. Cuando la interfaz de LAN inalámbrica también funciona como una red hospedada inalámbrica, la lista BSS contendrá una entrada para el BSS creado para la red hospedada inalámbrica.
La función WlanGetNetworkBssList devuelve ERROR_SUCCESS cuando el servicio WLAN AutoConfig devuelve una lista BSS vacía. Una aplicación que llama a la función WlanGetNetworkBssList debe comprobar que el miembro dwNumberOfItems del WLAN_BSS_LIST señalado por el parámetro ppWlanBssList no es cero antes de tener acceso al miembro wlanBssEntries[0] en WLAN_BSS_LIST estructura.
La función WlanGetNetworkBssList asigna memoria para la lista básica del conjunto de servicios que se devuelve en un búfer al que apunta el parámetro ppWlanBssList cuando la función se realiza correctamente. La memoria usada para el búfer a la que apunta el parámetro ppWlanBssList debe liberarse llamando a la función WlanFreeMemory después de que el búfer ya no sea necesario.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [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 |