WlanGetNetworkBssList 関数 (wlanapi.h)

[アーティクル]
10/19/2023

注意

一部の情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。

重要

この API は、2024 年秋に予定されているオペレーティングシステムの動作に対する今後の変更の影響を受けます。詳細については、「 Wi-Fi アクセスと場所に関する API 動作の変更」を参照してください。

WlanGetNetworkBssList 関数は、特定のワイヤレス LAN インターフェイス上のワイヤレスネットワークまたはネットワークの基本的なサービスセット (BSS) エントリの一覧を取得します。

構文

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

パラメーター

[in] hClientHandle

WlanOpenHandle 関数の以前の呼び出しによって取得されたクライアントのセッションハンドル。

[in] pInterfaceGuid

照会するワイヤレス LAN インターフェイスの GUID へのポインター。

ローカルコンピューターで有効になっている各ワイヤレス LAN インターフェイスの GUID は、 WlanEnumInterfaces 関数を使用して決定できます。

[optional] pDot11Ssid

BSS リストが要求されるネットワークの SSID を指定する DOT11_SSID 構造体へのポインター。このパラメーターは省略可能です。 NULL に設定すると、返されるリストには、ワイヤレス LAN インターフェイスで使用可能なすべての BSS エントリが含まれます。

DOT11_SSID構造体へのポインターを指定する場合、DOT11_SSID 構造体のuSSIDLength メンバーで指定される SSID の長さは、Wlantypes.h ヘッダーファイルで定義DOT11_SSID_MAX_LENGTH以下である必要があります。さらに、 dot11BssType パラメーターを dot11_BSS_type_infrastructure または dot11_BSS_type_independent に設定し、 bSecurityEnabled パラメーターを指定する必要があります。

[in] dot11BssType

ネットワークの BSS の種類。このパラメーターは、BSS リストのネットワークの SSID が指定されていない場合は無視されます ( pDot11Ssid パラメーターは NULL です)。

このパラメーターには、Wlantypes.h ヘッダーファイルで定義されているDOT11_BSS_TYPE列挙で定義されている次のいずれかの値を指定できます。

値	意味
dot11_BSS_type_infrastructure	インフラストラクチャ BSS ネットワーク。
dot11_BSS_type_independent	独立した BSS (IBSS) ネットワーク (アドホックネットワーク)。
dot11_BSS_type_any	BSS ネットワーク。

[in] bSecurityEnabled

ネットワークでセキュリティが有効になっているかどうかを示す値。このパラメーターは、BSS リストのネットワークの SSID が指定されている場合にのみ有効です ( pDot11Ssid パラメーターが NULL ではありません)。

pReserved

将来利用するために予約されています。このパラメーターは NULL に設定する必要があります。

[out] ppWlanBssList

WLAN_BSS_LIST構造体内の BSS エントリの返されたリストを受け取るためのポインターのストレージへのポインター。

呼び出しが成功した場合、返される WLAN_BSS_LIST のバッファーは WlanGetNetworkBssList 関数によって割り当てられます。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値は次のいずれかの戻りコードになる可能性があります。

リターンコード	説明
ERROR_INVALID_HANDLE	ハンドルテーブルにハンドル hClientHandle が見つかりませんでした。
ERROR_INVALID_PARAMETER	パラメーターが正しくありません。 hClientHandle、pInterfaceGuid、または ppWlanBssList パラメーターが NULL の場合、このエラーが返されます。 pReserved が NULL でない場合、このエラーが返されます。このエラーは、 hClientHandle、 pDot11Ssid パラメーターで指定された SSID、または dot11BssType パラメーターで指定された BSS 型が無効な場合にも返されます。
ERROR_NDIS_DOT11_POWER_STATE_INVALID	インターフェイスに関連付けられている無線はオフになっています。無線がオフの場合、BSS リストは使用できません。
ERROR_NOT_ENOUGH_MEMORY	この要求を処理し、クエリ結果にメモリを割り当てるために十分なメモリがありません。
ERROR_NOT_FOUND	要素が見つかりませんでした。このエラーは、 pInterfaceGuid パラメーターで指定されたクエリ対象のインターフェイスの GUID が見つからなかった場合に返されます。
ERROR_NOT_SUPPORTED	要求はサポートされていません。この関数が SP3 の Windows XP から呼び出された場合、または SP2 クライアントを使用した Windows XP 用ワイヤレス LAN API から呼び出された場合、このエラーが返されます。このエラーは、WLAN AutoConfig サービスが無効になっている場合にも返されます。
ERROR_SERVICE_NOT_ACTIVE	WLAN AutoConfig サービスが開始されていません。
RPC_STATUS	さまざまなエラーコード。

注釈

WlanGetNetworkBssList 関数は、特定のインターフェイスでアクセスできる各ワイヤレスネットワークまたはネットワークの基本的なサービスセットリストを取得します。各ワイヤレスネットワークに対して返される情報の一覧には、インフラストラクチャ BSS ネットワークの各アクセスポイントまたは独立した BSS ネットワーク (アドホックネットワーク) のネットワークピアによって返される情報要素の一覧も含まれています。情報は、ppWlanBssList パラメーターのWLAN_BSS_LIST構造体へのポインターとして返されます。 WLAN_BSS_LIST構造体には、項目数の後にWLAN_BSS_ENTRY構造体エントリの配列が含まれます。

WlanGetNetworkBssList 関数によって返される情報は、インフラストラクチャ BSS ネットワークのアクセスポイントまたは独立した BSS ネットワーク (アドホックネットワーク) のネットワークピアによって送信されるため、返される情報は信頼できません。 WLAN_BSS_ENTRY構造体の ulIeOffset メンバーと ulIeSize メンバーは、情報要素データ BLOB 自体のデータではなく、WLAN_BSS_ENTRY構造体内の情報要素データ BLOB のサイズを決定するために使用する必要があります。 WlanGetNetworkBssList 関数は、ulIeOffset メンバーが指す情報要素データ BLOB で返される情報が、ワイヤレス LAN の IEEE 802.11 標準で定義されている有効な情報要素であることを検証しません。

pDot11Ssid パラメーターが (NULL ではなく) 指定されている場合、指定された dot11BssType パラメーターは、インフラストラクチャ BSS ネットワークの場合はdot11_BSS_type_infrastructureに設定するか、独立した BSS ネットワーク (アドホックネットワーク) の場合はdot11_BSS_type_independentに設定する必要があります。 dot11BssType パラメーターが dot11_BSS_type_any に設定されている場合、WlanGetNetworkBssList 関数はERROR_SUCCESSを返しますが、BSS エントリは返されません。

ワイヤレス LAN インターフェイス上のすべてのインフラストラクチャ BSS ネットワークと独立した BSS ネットワーク (アドホックネットワーク) の一覧を返すには、 pDot11Ssid パラメーターを NULL に設定 します。ワイヤレス LAN インターフェイスがワイヤレスホステッドネットワークとしても動作している場合、BSS リストには、ワイヤレスホステッドネットワーク用に作成された BSS のエントリが含まれます。

WLANGetNetworkBssList 関数は、空の BSS リストが WLAN AutoConfig サービスによって返されたときにERROR_SUCCESSを返します。 WlanGetNetworkBssList 関数を呼び出すアプリケーションでは、ppWlanBssList パラメーターが指すWLAN_BSS_LISTの dwNumberOfItems メンバーが 0 ではないことをチェックしてから、WLAN_BSS_LIST構造体の wlanBssEntries[0] メンバーにアクセスする必要があります。

WlanGetNetworkBssList 関数は、関数が成功したときに ppWlanBssList パラメーターによって指されるバッファーで返される基本的なサービスセットリストにメモリを割り当てます。 ppWlanBssList パラメーターによって指されるバッファーに使用されるメモリは、バッファーが不要になった後に WlanFreeMemory 関数を呼び出すことによって解放する必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	wlanapi.h (Wlanapi.h を含む)
Library	Wlanapi.lib
[DLL]	Wlanapi.dll