WlanScan 関数 (wlanapi.h)

注

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

Important

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

WlanScan 関数は、指定されたインターフェイスで使用可能なネットワークのスキャンを要求します。

構文

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

パラメーター

[in] hClientHandle

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

[in] pInterfaceGuid

クエリを実行するインターフェイスの GUID。

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

[in, optional] pDot11Ssid

スキャンするネットワークの SSID を指定する DOT11_SSID 構造体へのポインター。このパラメーターには NULL を指定できます。 Windows XP SP3 とワイヤレス LAN API for Windows XP SP2: このパラメーターは NULL である必要があります。

[in, optional] pIeData

プローブ要求に含める情報要素へのポインター。このパラメーターは、クライアントプロビジョニングの可用性情報と 802.1X 認証要件を含む可能性があるWLAN_RAW_DATA構造を指します。Windows XP SP3 とワイヤレス LAN API for Windows XP SP2: このパラメーターは NULL である必要があります。

pReserved

将来の使用のために予約済み。 NULL に設定する必要があります。

戻り値

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

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

リターンコード	Description
ERROR_INVALID_PARAMETER	hClientHandle が NULL または無効、 pInterfaceGuid が NULL、または pReserved が NULL ではありません。
ERROR_INVALID_HANDLE	ハンドル hClientHandle がハンドルテーブルに見つかりませんでした。
RPC_STATUS	さまざまなエラーコード。
ERROR_NOT_ENOUGH_MEMORY	クエリ結果のメモリを割り当てませんでした。

注釈

WlanScan 関数は、ネイティブの 802.11 ワイヤレス LAN ドライバーが使用可能なワイヤレスネットワークをスキャンすることを要求します。ドライバーは、実装と pDot11Ssid および pIeData パラメーターで渡された値に応じて、プローブ要求 (アクティブスキャン) を送信する場合と送信しない場合があります。

pIeData パラメーターが NULL でない場合、ドライバーはスキャン中にプローブ要求を送信します。プローブ要求には、 pIeData パラメーターが指す情報要素 (IE) が含まれます。たとえば、Wi-Fi 保護されたセットアップ (WPS) IE は、WPS 対応のアクセスポイントを検出するためのプローブ要求に含めることができます。 pIeData パラメーターが指すバッファーには、要素 ID から始まる完全な IE が含まれている必要があります。

WlanScan 関数に渡される pIeData パラメーターには、近接サービス探索 (PSD) IE データエントリを含むオプションのWLAN_RAW_DATA構造体へのポインターを含めることができます。

PSD IE の格納に使用する場合、Wlanapi.h ヘッダーファイルで定義されているDOT11_PSD_IE_MAX_DATA_SIZE定数は dwDataSize メンバーの最大値です。

定数	価値	Description
DOT11_PSD_IE_MAX_DATA_SIZE	240	PSD IE データエントリの最大データサイズ (バイト単位)。

PSD IE の形式の説明を含む PSD IEs の詳細については、 WlanSetPsdIEDataList 関数を参照してください。

WlanScan 関数が呼び出されると、ネイティブの 802.11 ワイヤレス LAN ドライバーは、スキャンが開始される前に、使用可能なワイヤレスネットワークの現在のリストをフラッシュする可能性があります。アプリケーションでは、 WlanScan 関数を呼び出すと、 WlanGetNetworkBssList または WlanGetAvailableNetworkList 関数によって以前のスキャンから返された使用可能なワイヤレスネットワークの既存の一覧に追加されることを想定しないでください。

WlanScan 関数はすぐに返されます。ネットワークスキャンが完了したときに通知を受け取るために、Windows Vista 以降のクライアントは WlanRegisterNotification を呼び出して通知に登録する必要があります。 WlanRegisterNotification 関数に渡される dwNotifSource パラメーターには、自動構成モジュールによって生成された通知に登録するWLAN_NOTIFICATION_SOURCE_ACM ビットが設定されている必要があります。 Windows ロゴの要件を満たすワイヤレスネットワークドライバーは、 WlanScan 関数要求を 4 秒で完了する必要があります。

ワイヤレス LAN サービスは、使用可能なワイヤレスネットワークの変更時に通知を送信しません。ワイヤレス LAN サービスは、複数のスキャンで使用可能なネットワークの一覧の変更を追跡しません。現在の既定の動作では、ワイヤレス LAN サービスはワイヤレスインターフェイスドライバーに対して 60 秒ごとにワイヤレスネットワークのスキャンのみを要求し、場合によっては (既にワイヤレスネットワークに接続されている場合)、ワイヤレス LAN サービスはスキャンをまったく要求しません。 WlanScan 機能は、アプリケーションがワイヤレスネットワークの変更を追跡するために使用できます。アプリケーションは、最初にWLAN_NOTIFICATION_SOURCE_ACM通知に登録する必要があります。 その後、WlanScan 関数を呼び出してスキャンを開始できます。アプリケーションは、4 秒後にwlan_notification_acm_scan_complete通知またはタイムアウトの受信を待機する必要があります。その後、アプリケーションは WlanGetNetworkBssList または WlanGetAvailableNetworkList 関数を呼び出して、使用可能なワイヤレスネットワークの一覧を取得できます。このプロセスは、アプリケーションが使用可能なワイヤレスネットワークへの変更を追跡し続けることで、定期的に繰り返すことができます。

WlanScan 関数はすぐに戻り、スキャンが Windows XP SP3 または Windows XP 用ワイヤレス LAN API SP2 で完了したときに通知を提供しません。

スキャンの実行中にワイヤレスインターフェイスでデータパケットの送受信が困難になるため、 WlanScan 関数はネットワークスキャンが完了するまでの待機時間を長くする可能性があります。

Requirements

Requirement	価値
サポートされる最小クライアント	Windows Vista、WINDOWS XP SP3 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
Header	wlanapi.h (Wlanapi.h を含む)
Library	Wlanapi.lib
DLL	Wlanapi.dll
再頒布可能	Windows XP 用ワイヤレス LAN API SP2