WlanGetNetworkBssList function (wlanapi.h)

The WlanGetNetworkBssList function retrieves a list of the basic service set (BSS) entries of the wireless network or networks on a given wireless LAN interface.

Syntax

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

Parameters

[in] hClientHandle

The client's session handle, obtained by a previous call to the WlanOpenHandle function.

[in] pInterfaceGuid

A pointer to the GUID of the wireless LAN interface to be queried.

The GUID of each wireless LAN interface enabled on a local computer can be determined using the WlanEnumInterfaces function.

[optional] pDot11Ssid

A pointer to a DOT11_SSID structure that specifies the SSID of the network from which the BSS list is requested. This parameter is optional. When set to NULL, the returned list contains all of available BSS entries on a wireless LAN interface.

If a pointer to a DOT11_SSID structure is specified, the SSID length specified in the uSSIDLength member of DOT11_SSID structure must be less than or equal to DOT11_SSID_MAX_LENGTH defined in the Wlantypes.h header file. In addition, the dot11BssType parameter must be set to either dot11_BSS_type_infrastructure or dot11_BSS_type_independent and the bSecurityEnabled parameter must be specified.

[in] dot11BssType

The BSS type of the network. This parameter is ignored if the SSID of the network for the BSS list is unspecified (the pDot11Ssid parameter is NULL).

This parameter can be one of the following values defined in the DOT11_BSS_TYPE enumeration defined in the Wlantypes.h header file.

[in] bSecurityEnabled

A value that indicates whether security is enabled on the network. This parameter is only valid when the SSID of the network for the BSS list is specified (the pDot11Ssid parameter is not NULL).

pReserved

Reserved for future use. This parameter must be set to NULL.

[out] ppWlanBssList

A pointer to storage for a pointer to receive the returned list of BSS entries in a WLAN_BSS_LIST structure.

The buffer for the WLAN_BSS_LIST returned is allocated by the WlanGetNetworkBssList function if the call succeeds.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value may be one of the following return codes.

Remarks

The WlanGetNetworkBssList function retrieves the basic service set list for each wireless network or networks accessible on a given interface. The list of information returned for each wireless network also contains a list of information elements returned by each access point for an infrastructure BSS network or a network peer for an independent BSS network (ad hoc network). The information is returned as a pointer to an WLAN_BSS_LIST structure in the ppWlanBssList parameter. The WLAN_BSS_LIST structure contains an item count followed by an array of WLAN_BSS_ENTRY structure entries.

Since the information returned by the WlanGetNetworkBssList function is sent by an access point for an infrastructure BSS network or by a network peer for an independent BSS network (ad hoc network), the information returned should not be trusted. The ulIeOffset and ulIeSize members in the WLAN_BSS_ENTRY structure should be used to determine the size of the information element data blob in the WLAN_BSS_ENTRY structure, not the data in the information element data blob itself. The WlanGetNetworkBssList function does not validate that any information returned in the information element data blob pointed to by the ulIeOffset member is a valid information element as defined by the IEEE 802.11 standards for wireless LANs.

If the pDot11Ssid parameter is specified (not NULL), then the dot11BssType parameter specified must be set to either dot11_BSS_type_infrastructure for an infrastructure BSS network or dot11_BSS_type_independent for an independent BSS network (ad hoc network). If the dot11BssType parameter is set to dot11_BSS_type_any, then the WlanGetNetworkBssList function returns ERROR_SUCCESS but no BSS entries will be returned.

To return a list of all the infrastructure BSS networks and independent BSS networks (ad hoc networks) on a wireless LAN interface, set the pDot11Ssid parameter to NULL. When the wireless LAN interface is also operating as a Wireless Hosted Network , the BSS list will contain an entry for the BSS created for the Wireless Hosted Network.

The WlanGetNetworkBssList function returns ERROR_SUCCESS when an empty BSS list is returned by the WLAN AutoConfig Service. An application that calls the WlanGetNetworkBssList function must check that the dwNumberOfItems member of the WLAN_BSS_LIST pointed to by the ppWlanBssList parameter is not zero before accessing the wlanBssEntries[0] member in WLAN_BSS_LIST structure.

The WlanGetNetworkBssList function allocates memory for the basic service set list that is returned in a buffer pointed to by the ppWlanBssList parameter when the function succeeds. The memory used for the buffer pointed to by ppWlanBssList parameter should be released by calling the WlanFreeMemory function after the buffer is no longer needed.

Requirements

See also

WLAN_AVAILABLE_NETWORK

WLAN_AVAILABLE_NETWORK_LIST

WLAN_BSS_ENTRY

WLAN_BSS_LIST

WlanEnumInterfaces

WlanFreeMemory

WlanGetAvailableNetworkList

WlanScan