Google 致力于为黑人社区推动种族平等。查看具体举措

WLAN 感知概览

WLAN 感知功能使搭载 Android 8.0(API 级别 26)及更高版本的设备能够发现彼此并直接进行连接,它们之间无需任何其他类型的连接。WLAN 感知也称为“邻近感知网络”(NAN)。

WLAN 感知网络的工作原理是与邻近设备组建集群,如果设备是某个区域的第一个设备,则创建一个新集群。此集群行为适用于整个设备,由 WLAN 感知系统服务管理;应用无法控制集群行为。应用使用 WLAN 感知 API 与 WLAN 感知系统服务通信,后者管理设备上的 WLAN 感知硬件。

应用可通过 WLAN 感知 API 执行以下操作:

  • 发现其他设备:此 API 具有查找其他附近设备的机制。此过程会在一台设备发布一项或多项可发现服务时启动。然后,当设备订阅一项或多项服务并进入发布者的 WLAN 范围时,订阅者会收到一条告知已发现匹配发布者的通知。在订阅者发现发布者后,订阅者可以发送短消息或与发现的设备建立网络连接。设备可以既是发布者又是订阅者。

  • 创建网络连接:两台设备发现彼此后,可以创建没有接入点的双向 WLAN 感知网络连接。

蓝牙连接相比,WLAN 感知网络连接支持的覆盖范围更广,支持的吞吐率更高。这些类型的连接适用于在用户之间共享大量数据的应用,例如照片共享应用。

初始设置

要将您的应用设置为使用 WLAN 感知发现和网络,请执行以下步骤:

  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.ACCESS_FINE_LOCATION" />
        
  2. 使用 PackageManager API 检查设备是否支持 WLAN 感知功能,如下所示:

    Kotlin

        context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_AWARE)
        

    Java

        context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_AWARE);
        
  3. 检查 WLAN 感知功能当前是否可用。设备上可能存在 WLAN 感知功能,但当前可能无法使用,因为用户已停用 WLAN 或位置信息服务。如果正在使用 WLAN 直连、SoftAP 或网络共享,某些设备可能不支持 WLAN 感知功能,具体取决于其硬件和固件功能。要检查 WLAN 感知功能当前是否可用,请调用 isAvailable()

    WLAN 感知功能的可用性随时都可能发生变化。您的应用应注册 BroadcastReceiver 才能收到每当可用性发生变化时发送的 ACTION_WIFI_AWARE_STATE_CHANGED。应用收到该广播 Intent 后,应舍弃所有现有会话(假设 WLAN 感知服务已中断),然后检查当前的可用性状态并相应地调整其行为。例如:

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

如需了解详情,请参阅广播

获取会话

要开始使用 WLAN 感知功能,您的应用必须通过调用 attach() 获取 WifiAwareSession。此方法会执行以下操作:

  • 开启 WLAN 感知硬件。
  • 加入或组建 WLAN 感知集群。
  • 创建一个包含唯一命名空间的 WLAN 感知会话,该命名空间充当在其中创建的所有发现会话的容器。

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

您的应用只能调用 attach() 一次。如果您的应用调用 attach() 多次,则应用会为每次调用接收不同的会话,且每个会话都有自己的命名空间。这可能适用于复杂的情况,但通常应该避免。

发布服务

要使服务可检测到,请调用采用以下参数的 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() 回调方法。

发布后,当运行匹配订阅者应用的设备进入发布设备的 WLAN 范围时,订阅者会发现该服务。当订阅者发现发布者时,发布者不会收到通知;但是,如果订阅者向发布者发送消息,则发布者会收到通知。发生这种情况时,系统会调用 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() 来更新订阅会话。

此时,您的订阅等待匹配的发布者进入 WLAN 范围。出现这种情况时,系统会执行 onServiceDiscovered() 回调方法。您可以使用此回调中的 PeerHandle 参数向该发布者发送消息创建与该发布者的连接

要停止订阅某项服务,请调用 DiscoverySession.close()。发现会话与其父级 WifiAwareSession 关联。如果父级会话关闭,其关联的发现会话也会随之关闭。尽管舍弃的对象也会关闭,但系统无法保证超出范围的会话何时关闭,因此我们建议您明确调用 close() 方法。

发送消息

要向另一台设备发送消息,您需要以下对象:

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

虽然需要 PeerHandle 才能与对等设备进行通信,但您不应依赖它作为对等设备的永久标识符。应用可以使用更高级别的标识符,这些标识符嵌入在发现服务本身或后续消息中。您可以使用 PublishConfigSubscribeConfigsetMatchFilter()setServiceSpecificInfo() 方法在发现服务中嵌入标识符。setMatchFilter() 方法会影响发现,而 setServiceSpecificInfo() 方法不会影响发现。

在消息中嵌入标识符意味着修改消息字节数组以包含标识符(例如,作为前几个字节)。

创建连接

WLAN 感知功能支持两个 WLAN 感知设备之间的客户端-服务器网络连接。

要设置客户端-服务器连接,请执行以下操作:

  1. 使用 WLAN 感知发现功能(在服务器上)发布服务并(在客户端上)订阅服务

  2. 订阅者发现发布者后,从订阅者向发布者发送消息

  3. 在发布者设备上启动 ServerSocket,并设置或获取其端口:

    Kotlin

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

    Java

        ServerSocket ss = new ServerSocket(0);
        int port = ss.getLocalPort();
        
  4. 使用 ConnectivityManagerWifiAwareNetworkSpecifier 在发布者设备上请求 WLAN 感知网络,指定发现会话和订阅者的 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(networkRequest, 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(networkRequest, callback);
        
  5. 使用与发布者相同的方法在订阅者设备上请求 WLAN 感知网络。创建 NetworkSpecifier 时,请勿指定端口。当网络连接可用、已更改或丢失时,系统会调用相应的回调方法。

  6. 对订阅者调用 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);
        
  7. 完成网络连接后,请调用 unregisterNetworkCallback()

对等设备测距和位置感知发现

具有 WLAN RTT 位置功能的设备可以直接测量到对等设备的距离,并利用此信息限制 WLAN 感知服务发现。

WLAN RTT API 支持直接使用 WLAN 感知对等设备的 MAC 地址或 PeerHandle 测量到该设备的距离。

WLAN 感知发现功能可以被限制为仅发现特定地理围栏内的服务。例如,您可以设置地理围栏,以便发现发布 "Aware_File_Share_Service_Name" 服务且距离在 3 米(指定为 3000mm)到 10 米(指定为 10000mm)之间的设备。

要启用地理围栏,发布者和订阅者都必须采取操作:

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

    如果发布者未启用测距,则会忽略订阅者指定的任何地理围栏限制,并执行正常发现而忽略距离。

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

    对于任一值,未指定的距离表示没有限制。只指定最大距离意味着最小距离为 0。仅指定最小距离意味着没有最大值。

如果在地理围栏内发现对等服务,则会触发 onServiceDiscoveredWithinRange 回调,从而提供与对等设备的测量距离。然后,可以根据需要调用直接 WLAN RTT API,以便稍后测量距离。