Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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

应用可通过 WLAN 感知 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 发现和网络功能，请执行以下步骤：

在应用的清单中请求以下权限：

<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" />

使用 PackageManager API 检查设备是否支持 Wi-Fi Aware：

Kotlin

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_AWARE)

Java

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

检查 Wi-Fi Aware 是否可用。设备上可能存在 Wi-Fi Aware，但可能无法使用，因为用户已停用 Wi-Fi 或位置信息。根据硬件和固件功能，如果正在使用 WLAN 直连、SoftAP 或网络共享，某些设备可能不支持 Wi-Fi Aware。如需检查 Wi-Fi Aware 是否可用，请调用 isAvailable()。

WLAN 感知功能的可用性随时都可能发生变化。注册 BroadcastReceiver 以接收 ACTION_WIFI_AWARE_STATE_CHANGED，该广播会在可用性发生变化时发送。当应用收到广播 intent 时，请舍弃所有现有会话（假设 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。此方法会执行以下操作：

开启 WLAN 感知硬件。
加入或组建 WLAN 感知集群。
创建一个具有唯一命名空间的 Wi-Fi Aware 会话，该命名空间充当在其中创建的所有发现会话的容器。

如果应用成功附加，系统会执行 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() 回调方法。

发布后，当运行匹配订阅者应用的设备进入发布设备的 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。
- 您的应用订阅某项服务。然后，当发现匹配的发布者时，您的应用会从 onServiceDiscovered() 回调中获取发布者的 PeerHandle。

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

当对等设备成功收到消息后，系统会在发送应用中调用 onMessageSendSucceeded() 回调。
当对等设备收到消息时，系统会调用接收应用中的 onMessageReceived() 回调。

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

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

创建连接

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

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

使用 Wi-Fi Aware 发现功能发布服务和订阅服务。
订阅者发现发布者后，从订阅者向发布者发送消息。

在发布者设备上启动 ServerSocket，并设置或获取其端口：

Kotlin

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

Java

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

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

connMgr.requestNetwork(myNetworkRequest, callback);

发布商请求网络后，向订阅者发送消息。
订阅方收到发布方发送的消息后，请使用与发布方相同的方法在订阅方上请求 Wi-Fi Aware 网络。创建 NetworkSpecifier 时，请勿指定端口。当网络连接可用、发生更改或丢失时，系统会调用相应的回调方法。

在订阅者上调用 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);

当您使用完网络连接后，请调用 unregisterNetworkCallback()。

注意：构建网络请求和指定所需的网络功能并非 Wi-Fi Aware API 所独有。如需详细了解如何处理网络请求，请参阅 ConnectivityManager。

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

具有 Wi-Fi RTT 位置信息功能的设备可以直接测量与对等设备的距离，并使用此信息来限制 Wi-Fi Aware 服务发现。

Wi-Fi RTT API 允许使用 Wi-Fi Aware 对等设备的 MAC 地址或 PeerHandle 直接测距。

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

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

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

如果发布者未启用测距，则系统会忽略订阅者指定的任何地理围栏限制，并执行正常发现，忽略距离。
订阅者必须使用 setMinDistanceMm() 和 setMaxDistanceMm() 的某种组合来指定地理围栏。

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

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

Wi-Fi 感知概览 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Android 13（API 级别 33）增强功能

Android 12（API 级别 31）增强功能

初始设置

Kotlin

Java

Kotlin

Java

获取会话

发布服务

Kotlin

Java

订阅服务

Kotlin

Java

发送消息

创建连接

Kotlin

Java

Kotlin

Java

Kotlin

Java

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

Wi-Fi 感知概览