Wi-Fi 偵測總覽

透過 Wi-Fi Aware 功能，搭載 Android 8.0 (API 級別 26) 以上版本的裝置就能直接互相探索及連線，不必透過任何其他類型的連線方式。Wi-Fi Aware 也稱為鄰近感知網路 (NAN)。

Wi-Fi Aware 網路的運作方式為結合鄰近裝置的叢集，或 如果裝置位置內第一，請建立新叢集這項叢集行為會套用至整部裝置，並由 Wi-Fi Aware 系統服務管理；應用程式無法控制叢集行為。應用程式使用情形 Wi-Fi Aware API 連線至 Wi-Fi Aware 系統服務， 才能啟動裝置的 Wi-Fi 感知硬體

Wi-Fi Aware API 可讓應用程式執行下列作業：

• 探索其他裝置：這個 API 提供尋找其他裝置的機制 附近的裝置。這項程序會在一部裝置發布一部裝置時開始執行 或更多可探索的服務接著，當裝置訂閱一或多項服務並進入發布商的 Wi-Fi 範圍時，訂閱者就會收到通知，指出系統已找到符合條件的發布商。在 訂閱者找到發布者時，訂閱者可以 訊息，或與偵測到的裝置建立網路連線。 裝置可以同時為發布者和訂閱者。

• 建立網路連線：兩部裝置互相偵測後，即可在不透過存取點的情況下，建立雙向 Wi-Fi Aware 網路連線。

Wi-Fi Aware 網路連線支援更長的處理量傳輸速率 距離藍牙 連線狀態。這類連線很適合用於在使用者之間分享大量資料的應用程式，例如相片分享應用程式。

Android 13 (API 級別 33) 的強化功能

在搭載 Android 13 (API 級別 33) 以上版本且支援即時通訊模式的裝置上，應用程式可以使用 PublishConfig.Builder.setInstantCommunicationModeEnabled() 和 SubscribeConfig.Builder.setInstantCommunicationModeEnabled() 方法，為發布者或訂閱者探索工作階段啟用或停用即時通訊模式。即時通訊模式可以加快訊息交換速度 服務探索，以及任何為發布者或訂閱者設定的資料路徑 探索過程。判斷裝置是否支援即時通訊 模式，請使用 isInstantCommunicationModeSupported() 方法。

注意：由於即時通訊模式會使用額外電力，因此從發布者或訂閱者探索工作階段開始時起，這模式只會持續啟用 30 秒。

Android 12 (API 級別 31) 改善項目

Android 12 (API 級別 31) 為 Wi-Fi Aware 新增了幾項改善：

• 在搭載 Android 12 (API 級別 31) 以上版本的裝置中，您可以使用 onServiceLost() 當應用程式因為 服務停止或移出範圍外。
• 已成功設定 Wi-Fi Aware 資料路徑。較舊版本 使用 L2 訊息提供發起人的 MAC 位址， 但有些許延遲在搭載 Android 12 以上版本的裝置上，回應者 (伺服器) 可以設定為接受任何對等互連，也就是說 且預先知道啟動器的 MAC 位址。這可加快資料路徑啟動速度，並讓單一網路要求啟用多個點對點連結。
• 在 Android 12 以上版本中執行的應用程式可以使用 WifiAwareManager.getAvailableAwareResources() 方法，取得目前可用的資料路徑數量、發布工作階段和訂閱工作階段。這可協助應用程式判斷是否有足夠的可用資源，可執行所需的功能。

初始設定

如要設定應用程式使用 Wi-Fi Aware 探索和網路功能，請執行下列步驟：

1. 在應用程式資訊清單中要求下列權限：

   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
   <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
   <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
   <uses-permission android:name="android.permission.INTERNET" />
   <!-- If your app targets Android 13 (API level 33)
        or higher, you must declare the NEARBY_WIFI_DEVICES permission. -->
   <uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
                    <!-- If your app derives location information from
                         Wi-Fi APIs, don't include the "usesPermissionFlags"
                         attribute. -->
                    android:usesPermissionFlags="neverForLocation" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                    <!-- If any feature in your app relies on precise location
                         information, don't include the "maxSdkVersion"
                         attribute. -->
                    android:maxSdkVersion="32" />

2. 透過以下方式檢查裝置是否支援 Wi-Fi Aware： PackageManager API，如下所示：

   Kotlin

   context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_AWARE)

   Java

   context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_AWARE);

3. 確認目前是否可使用 Wi-Fi Aware。Wi-Fi Aware 可能位於 裝置，但目前可能因為使用者停用而無法使用 Wi-Fi 或位置資訊。部分裝置在使用 Wi-Fi Direct、SoftAP 或 Tethering 時，可能會因硬體和韌體功能而無法支援 Wi-Fi Aware。如要檢查 Wi-Fi Aware 目前是否可用，請呼叫 isAvailable()。

   Wi-Fi Aware 的可用性可能隨時變更。您的應用程式應 註冊BroadcastReceiver即可接收 ACTION_WIFI_AWARE_STATE_CHANGED, 每當有供應情形變更，系統就會傳送這個磁碟區。當應用程式收到廣播意圖時，應捨棄所有現有的工作階段 (假設 Wi-Fi Aware 服務中斷)，然後檢查目前的可用性狀態，並據此調整行為。例如：

   Kotlin

   val wifiAwareManager = context.getSystemService(Context.WIFI_AWARE_SERVICE) as WifiAwareManager?
   val filter = IntentFilter(WifiAwareManager.ACTION_WIFI_AWARE_STATE_CHANGED)
   val myReceiver = object : BroadcastReceiver() {
   
       override fun onReceive(context: Context, intent: Intent) {
           // discard current sessions
           if (wifiAwareManager?.isAvailable) {
               ...
           } else {
               ...
           }
       }
   }
   context.registerReceiver(myReceiver, filter)

   Java

   WifiAwareManager wifiAwareManager = 
           (WifiAwareManager)context.getSystemService(Context.WIFI_AWARE_SERVICE)
   IntentFilter filter =
           new IntentFilter(WifiAwareManager.ACTION_WIFI_AWARE_STATE_CHANGED);
   BroadcastReceiver myReceiver = new BroadcastReceiver() {
       @Override
       public void onReceive(Context context, Intent intent) {
           // discard current sessions
           if (wifiAwareManager.isAvailable()) {
               ...
           } else {
               ...
           }
       }
   };
   context.registerReceiver(myReceiver, filter);

詳情請參閱「廣播」。

注意：請務必先註冊廣播接收器，再檢查可用性。否則應用程式可能無法再順利運作 認為 Wi-Fi Aware 可以使用，但不會收到通知 異動

取得工作階段

如要開始使用 Wi-Fi Aware，應用程式必須呼叫 attach() 來取得 WifiAwareSession。此方法會執行以下操作：

• 開啟 Wi-Fi Aware 硬體。
• 加入或建立 Wi-Fi Aware 叢集。
• 使用不重複的命名空間建立 Wi-Fi Aware 工作階段，該命名空間會做為其中建立的所有探索工作階段的容器。

如果應用程式已成功附加，系統會執行 onAttached() 回呼。這個回呼會提供 WifiAwareSession 物件 應用程式應用於所有後續工作階段作業。應用程式可以使用這個工作階段發布服務或訂閱服務。

應用程式應呼叫 僅限attach()一次。如果應用程式多次呼叫 attach()，則應用程式會為每次呼叫接收不同的工作階段，每個工作階段都有自己的命名空間。這在複雜情況下可能很實用，但一般來說不建議使用。

注意： 只要有執行中的工作階段，系統就會維持同步處理作業 連線至 Wi-Fi Aware 叢集這類叢集會耗用資源和電池。為節省資源，請在不再需要工作階段時呼叫 WifiAwareSession.close()。

發布服務

如要讓服務可供探索，請呼叫 publish() 方法，該方法會採用下列參數：

• PublishConfig 會指定 服務和其他設定屬性，例如比對篩選器
• DiscoverySessionCallback 會指定事件發生時要執行的動作，例如訂閱者收到訊息時。

範例如下：

Kotlin

val config: PublishConfig = PublishConfig.Builder()
        .setServiceName(AWARE_FILE_SHARE_SERVICE_NAME)
        .build()
awareSession.publish(config, object : DiscoverySessionCallback() {

    override fun onPublishStarted(session: PublishDiscoverySession) {
        ...
    }

    override fun onMessageReceived(peerHandle: PeerHandle, message: ByteArray) {
        ...
    }
})

Java

PublishConfig config = new PublishConfig.Builder()
    .setServiceName(“Aware_File_Share_Service_Name”)
    .build();

awareSession.publish(config, new DiscoverySessionCallback() {
    @Override
    public void onPublishStarted(PublishDiscoverySession session) {
        ...
    }
    @Override
    public void onMessageReceived(PeerHandle peerHandle, byte[] message) {
        ...
    }
}, null);

如果發布成功， onPublishStarted() 回呼方法。

發布後，當執行相符訂閱者應用程式的裝置進入發布裝置的 Wi-Fi 範圍時，訂閱者就會發現這項服務。時間 訂閱者找到發布商後，發布者不會收到 通知；如果訂閱者傳送訊息給出版商，則 發布商會收到通知在這種情況下，系統會呼叫 onMessageReceived() 回呼方法。您可以使用此方法中的 PeerHandle 引數，傳送訊息回給訂閱者，或建立連線。

如要停止發布服務，請呼叫 DiscoverySession.close()。探索工作階段與家長相關聯 WifiAwareSession。如果父項工作階段 封閉式探索工作階段也已關閉。雖然已捨棄的物件也會關閉，但系統無法保證何時會關閉超出範圍的工作階段，因此建議您明確呼叫 close() 方法。

訂閱服務

如要訂閱服務，請呼叫 subscribe() 方法， 該參數會使用下列參數：

• SubscribeConfig 會指定要訂閱的服務名稱和其他設定屬性，例如比對篩選器。
• DiscoverySessionCallback 會指定事件發生時要執行的動作，例如發現發布商時。

範例如下：

Kotlin

val config: SubscribeConfig = SubscribeConfig.Builder()
        .setServiceName(AWARE_FILE_SHARE_SERVICE_NAME)
        .build()
awareSession.subscribe(config, object : DiscoverySessionCallback() {

    override fun onSubscribeStarted(session: SubscribeDiscoverySession) {
        ...
    }

    override fun onServiceDiscovered(
            peerHandle: PeerHandle,
            serviceSpecificInfo: ByteArray,
            matchFilter: List<ByteArray>
    ) {
        ...
    }
}, null)

Java

SubscribeConfig config = new SubscribeConfig.Builder()
    .setServiceName("Aware_File_Share_Service_Name")
    .build();

awareSession.subscribe(config, new DiscoverySessionCallback() {
    @Override
    public void onSubscribeStarted(SubscribeDiscoverySession session) {
        ...
    }

    @Override
    public void onServiceDiscovered(PeerHandle peerHandle,
            byte[] serviceSpecificInfo, List<byte[]> matchFilter) {
        ...
    }
}, null);

如果訂閱作業成功，系統會在應用程式中呼叫 onSubscribeStarted() 回呼。由於您可以在應用程式發現發布者後，使用回呼中的 SubscribeDiscoverySession 引數與發布者通訊，因此應儲存此參照。您隨時可以透過以下方法更新訂閱工作階段： 撥號中 updateSubscribe() 我會深入探討

此時，您的訂閱項目會等待相符發布者加入 Wi-Fi 範圍。發生這種情況時，系統會執行 onServiceDiscovered() 回呼方法。您可以使用 PeerHandle 引數，以便傳送訊息或 連結該發布商。

如要停止訂閱服務，請呼叫 DiscoverySession.close()。探索工作階段與家長相關聯 WifiAwareSession。如果父項工作階段 封閉式探索工作階段也已關閉。雖然已捨棄的物件也會關閉，但系統無法保證何時會關閉超出範圍的工作階段，因此建議您明確呼叫 close() 方法。

傳送訊息

如要傳送訊息至其他裝置，您需要下列物件：

• DiscoverySession。這個物件可讓您 通話 sendMessage()。 應用程式可以透過發布服務或訂閱服務來取得 DiscoverySession。

• 其他裝置的 PeerHandle，以便轉送 撰寫新的電子郵件訊息應用程式會透過下列任一方式取得其他裝置的 PeerHandle：

  • 您的應用程式發布服務，並收到訂閱者傳送的訊息。 應用程式會取得訂閱者的 來自onMessageReceived()的PeerHandle 回呼。
  • 您的應用程式訂閱服務。接著，當 Google 偵測到 這樣您的應用程式就會從發布商的廣告請求中獲得 PeerHandle 的 onServiceDiscovered() 回呼。

如要傳送訊息，請呼叫 sendMessage()。接著可能會發生下列回呼：

• 對等點成功收到訊息後，系統會呼叫 onMessageSendSucceeded() 傳送應用程式中的回呼。
• 當對等端收到訊息時，系統會在接收應用程式中呼叫 onMessageReceived() 回呼。

注意： 訊息通常用於簡易訊息，因為 送達 (或訂購商品缺貨或重複)，且上限為 長度約 255 位元組如要判斷確切長度限制，請呼叫 getMaxServiceSpecificInfoLength()。如要進行高速雙向通訊，您的應用程式應 請改為建立連線。

雖然與同類應用程式通訊時需要使用 PeerHandle，但請勿 並視為對等的永久 ID。高階 ID 可以是 內嵌於探索服務本身，或位於 後續訊息。您可以使用 PublishConfig 或 SubscribeConfig 的 setMatchFilter() 或 setServiceSpecificInfo() 方法，在探索服務中嵌入 ID。setMatchFilter() 方法會影響探索，而 setServiceSpecificInfo() 方法不會影響探索。

在訊息中嵌入 ID 表示修改訊息位元組陣列，以便納入 ID (例如，前幾個位元組)。

建立連線

Wi-Fi Aware 支援在兩部 Wi-Fi Aware 裝置之間使用用戶端伺服器網路。

如要設定用戶端與伺服器連線：

1. 使用 Wi-Fi Aware 探索功能，在伺服器上發布服務，並在用戶端上訂閱服務。

2. 訂閱者找到發布者後 訂閱者傳送訊息給發布商。

3. 為發布商啟動 ServerSocket ，接著設定或取得其連接埠：

   Kotlin

   val ss = ServerSocket(0)
   val port = ss.localPort

   Java

   ServerSocket ss = new ServerSocket(0);
   int port = ss.getLocalPort();

4. 使用 ConnectivityManager： 使用 WifiAwareNetworkSpecifier、 並指定探索工作階段 訂閱者的 PeerHandle， 從訂閱者傳送的訊息中取得：

   Kotlin

   val networkSpecifier = WifiAwareNetworkSpecifier.Builder(discoverySession, peerHandle)
       .setPskPassphrase("somePassword")
       .setPort(port)
       .build()
   val myNetworkRequest = NetworkRequest.Builder()
       .addTransportType(NetworkCapabilities.TRANSPORT_WIFI_AWARE)
       .setNetworkSpecifier(networkSpecifier)
       .build()
   val callback = object : ConnectivityManager.NetworkCallback() {
       override fun onAvailable(network: Network) {
           ...
       }
   
       override fun onCapabilitiesChanged(network: Network, networkCapabilities: NetworkCapabilities) {
           ...
       }
   
       override fun onLost(network: Network) {
           ...
       }
   }
   
   connMgr.requestNetwork(myNetworkRequest, callback);

   Java

   NetworkSpecifier networkSpecifier = new WifiAwareNetworkSpecifier.Builder(discoverySession, peerHandle)
       .setPskPassphrase("somePassword")
       .setPort(port)
       .build();
   NetworkRequest myNetworkRequest = new NetworkRequest.Builder()
       .addTransportType(NetworkCapabilities.TRANSPORT_WIFI_AWARE)
       .setNetworkSpecifier(networkSpecifier)
       .build();
   ConnectivityManager.NetworkCallback callback = new ConnectivityManager.NetworkCallback() {
       @Override
       public void onAvailable(Network network) {
           ...
       }
   
       @Override
       public void onCapabilitiesChanged(Network network, NetworkCapabilities networkCapabilities) {
           ...
       }
   
       @Override
       public void onLost(Network network) {
           ...
       }
   };
   
   ConnectivityManager connMgr.requestNetwork(myNetworkRequest, callback);

5. 發布商要求網路後，應傳送訊息給訂閱者。

6. 訂閱者收到發布者傳來的訊息後，請要求 Wi-Fi 連線 訂閱者使用與發布商相同的方法提升品牌知名度。建立 NetworkSpecifier 時，請勿指定連接埠。 網路連線 可用、變更或遺失

7. 在訂閱者上呼叫 onAvailable() 方法後， Network 物件由以下服務提供： 您可以開啟 Socket 與發布商的 ServerSocket 互動，但您必須瞭解 ServerSocket 的 IPv6 位址和通訊埠。您可以從 onCapabilitiesChanged() 回呼中提供的 NetworkCapabilities 物件取得這些值：

   Kotlin

   val peerAwareInfo = networkCapabilities.transportInfo as WifiAwareNetworkInfo
   val peerIpv6 = peerAwareInfo.peerIpv6Addr
   val peerPort = peerAwareInfo.port
   ...
   val socket = network.getSocketFactory().createSocket(peerIpv6, peerPort)

   Java

   WifiAwareNetworkInfo peerAwareInfo = (WifiAwareNetworkInfo) networkCapabilities.getTransportInfo();
   Inet6Address peerIpv6 = peerAwareInfo.getPeerIpv6Addr();
   int peerPort = peerAwareInfo.getPort();
   ...
   Socket socket = network.getSocketFactory().createSocket(peerIpv6, peerPort);

8. 網路連線完成後，請呼叫 unregisterNetworkCallback()。

   注意：建立網路要求並指定所需的網路功能，並非 Wi-Fi Aware API 專屬。如要進一步瞭解如何使用網路要求，請參閱 ConnectivityManager。

選擇同類應用程式及可辨識位置的探索方式

已安裝 Wi-Fi 即時文字訊息位置資訊的裝置 可直接測量與同類應用程式的距離，並使用這項資訊 限制 Wi-Fi Aware 服務探索。

Wi-Fi RTT API 可讓您使用 MAC 位址或其 PeerHandle。

Wi-Fi Aware 探索功能可限制只探索特定地理圍欄內的服務。舉例來說，您可以設定地理空間範圍，讓裝置在 3 公尺 (指定為 3,000 公釐) 以內，且不超過 10 公尺 (指定為 10,000 公釐) 的範圍內，即可發現發布 "Aware_File_Share_Service_Name" 服務的裝置。

如要啟用地理圍欄功能，發布者和訂閱者都必須採取行動：

• 發布者必須使用 setRangingEnabled(true) 在已發布服務上啟用測距功能。

  如果發布者未啟用測距功能，系統會忽略訂閱者指定的任何地理邊界限制，並執行一般探索作業，忽略距離。

• 訂閱者必須使用 setMinDistanceMm 和 setMaxDistanceMm 的組合來指定地理圍欄。

  無論是哪個值，未指定距離即表示沒有限制。僅指定最大距離，表示最小距離為 0。只有指定 最小距離表示無上限。

如果在地理圍欄內發現對等互連服務， onServiceDiscoveredWithinRange 觸發回呼，進而提供與對等點之間的測量距離。 然後視需要呼叫直接 Wi-Fi RTT API，以測量距離 再聯絡。