Wi-Fi Aware 概述

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 Aware 硬件。

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()方法。

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. 使用以下所示的 PackageManager API 检查设备是否支持 Wi-Fi Aware。

   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 或网络共享，某些设备可能不支持 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，您的应用必须通过调用 attach() 获取一个 WifiAwareSession。此方法执行以下操作：

• 打开 Wi-Fi Aware 硬件。
• 加入或形成 Wi-Fi Aware 集群。
• 创建一个具有唯一命名空间的 Wi-Fi Aware 会话，该命名空间充当在其内创建的所有发现会话的容器。

如果应用成功附加，系统将执行 onAttached() 回调。此回调提供了一个 WifiAwareSession 对象，您的应用应将其用于所有后续会话操作。应用可以使用此会话来 发布服务 或 订阅服务。

您的应用应仅调用一次 attach()。如果您的应用多次调用 attach()，则应用将为每次调用接收一个不同的会话，每个会话都有自己的命名空间。这在复杂场景中可能很有用，但通常应避免。

发布服务

要使服务可发现，请调用 publish() 方法，该方法采用以下参数：

• PublishConfig 指定服务名称和其他配置属性，例如匹配过滤器。
• DiscoverySessionCallback 指定在事件发生时执行的操作，例如订阅者收到消息时。

以下是一个示例。

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) {
        ...
    }
})

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 指定在事件发生时执行的操作，例如发现发布者时。

以下是一个示例。

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)

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。
  • 您的应用订阅服务。然后，当它发现匹配的发布者时，您的应用从 onServiceDiscovered() 回调中获取发布者的 PeerHandle。

要发送消息，请调用 sendMessage()。然后可能会发生以下回调：

• 当对等方成功接收消息时，系统将在发送应用中调用 onMessageSendSucceeded() 回调。
• 当对等方收到消息时，系统将在接收应用中调用 onMessageReceived() 回调。

尽管PeerHandle是与对等节点通信所必需的，但您不应将其视为对等节点的永久标识符。应用程序可以使用更高级别的标识符，这些标识符可以嵌入到发现服务本身或后续消息中。您可以使用setMatchFilter()或setServiceSpecificInfo()方法将标识符嵌入到发现服务中，这些方法属于PublishConfig或SubscribeConfig。 setMatchFilter()方法会影响发现，而setServiceSpecificInfo()方法不会影响发现。

将标识符嵌入消息意味着修改消息字节数组以包含标识符（例如，作为前几个字节）。

创建连接

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在发布者上请求 Wi-Fi Aware 网络，并指定发现会话和订阅者的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 Aware 网络。创建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 RTT 定位功能的设备可以直接测量到对等节点的距离，并使用此信息来约束 Wi-Fi Aware 服务发现。

Wi-Fi RTT API 允许使用其 MAC 地址或其PeerHandle直接测距到 Wi-Fi Aware 对等节点。

Wi-Fi Aware 发现可以限制为仅发现特定地理围栏内的服务。例如，您可以设置一个地理围栏，允许发现发布“Aware_File_Share_Service_Name”服务的设备，该设备的距离不小于 3 米（指定为 3,000 毫米），不大于 10 米（指定为 10,000 毫米）。

要启用地理围栏，发布者和订阅者都必须采取措施。

• 发布者必须使用setRangingEnabled(true)在发布的服务上启用测距。

  如果发布者未启用测距，则订阅者指定的任何地理围栏约束都将被忽略，并且会执行正常的发现，忽略距离。

• 订阅者必须使用setMinDistanceMm和setMaxDistanceMm的某种组合来指定地理围栏。

  对于这两个值，未指定的距离表示没有限制。仅指定最大距离表示最小距离为 0。仅指定最小距离表示没有最大值。

当在地理围栏内发现对等服务时，将触发onServiceDiscoveredWithinRange回调，该回调提供到对等节点的测量距离。然后可以根据需要调用直接 Wi-Fi RTT API 以在以后的时间测量距离。