A-设备连接状态管理

一、设备连接状态的刷新

开发 APP 的时候经常需要显示设备的连接状态，很多用例也依赖于设备的连接状态（例如控制设备的时候要求设备在线）。所以如何准确地在 APP 与设备之间同步连接状态是我们首先要解决的问题。

1、获取设备连接状态

设备状态可以通过 xDevice.getConnectionState() 从设备实体中取出，代码如下：

//deviceTag由设备MAC与PID生成,可直接从设备对象中获取到,具体请参考版本差异变更中的描述
XDevice device = XLinkSDK.getDeviceMananger().getDevice(deviceTag);
XDevice.State connectionState = device.getConnectionState();

2、设备连接状态类型

对于连接状态，一个设备默认情况下允许获取到三种状态（连接状态是仅可读的，不允许进行修改,由内部设备维护管理对象维护）

连接状态	意义	使用场景
getLocalConnectionState()	获取当前设备的内网连接状态(内网)	当设备仅需要进行内网控制或者是允许进行内网控制时，或者关心设备的内网连接状态时，都可以从此状态获取最新的内网连接状态
getCloudConnectionState()	获取当前设备的云端连接状态(外网)	当设备仅需要进行外网控制或者是允许进行外网控制时，或者关心设备的外网连接状态时，都可以从此状态获取最新的云端连接状态
getConnectionState()	获取当前设备的连接状态	只要内网或者外网任何一个连接中，该状态值都会返回连接中的状态，当全部断开连接时才会返回断开连接状态

大部分使用情况下，通过 getConnectionState() 关注设备的连接状态正常即可进行设备的控制。在对设备有特殊环境需求时则可以考虑其它的相关的状态值

对于设备返回的连接状态，主要有三种

状态值	意义
DISCONNECTED	断开连接,或者当前没有连接,设备无法正常通讯
CONNECTING	设备正在尝试连接中
CONNECTED	设备连接成功,设备允许正常通讯

3、订阅设备状态变化

开发者可以订阅设备的状态变化，通过 XAPP SDK 初始化配置设置状态监听，请参考[进阶篇-SDK基本配置](A-XAPP SDK 基本配置.md)。也可以通过设备管理对象对设备状态监听进行注册

//直接对设备管理对象注册设备状态监听事件
XLinkDeviceManager.getInstance()
    .addDeviceStateListener(new XLinkDeviceStateListener() {
        @Override
        public void onDeviceStateChanged(XDevice xDevice, XDevice.State status) {
        }
});
 
 
 
//取消监听事件的注册
XLinkDeviceManager.getInstance().removeDeviceStateListener(mDeviceStateListener);

设备管理对象对所有注册的监听事件将会保持引用，所以请务必记得取消订阅以免引起内存泄漏

简单地说，如果开发者不关心设备与 XAPP SDK 的连接方式，只需处理 getConnectionState() 即可当 getConnectionState() 返回CONNECTED时，开发者可向设备发送或请求数据。

4、连接策略处理——自v2版本起

v6.2版本更新新增了是否开启内网自动连接功能，该功能默认是不开启的，即默认情况下是不会尝试内网连接设备的。而此前版本中，由于没有默认情况下都是自动进行内网连接的，所以请注意此处变更。

4.1、设备添加

设备添加时是可选添加后的内网连接设置的，原配置默认为内网自动连接，v6.2版本默认为不进行内网自动连接，如果需要保留该内网自动连接功能，请注意更新该配置。

XLinkAddDeviceTask task = XLinkAddDeviceTask.newBuilder()
        //是否在添加成功后进行内网连接，此处相当于设置内网连接策略为自动连接
        //默认为false，相当于不需要内网连接
        .setConnectLocal(true)
        ...
        .build();
XLinkSDK.startTask(task);

注：

原有添加设备时必定会进行内网的连接，所以实际上添加完之后是保持着内网连接的状态的，若不设置connectLocal的参数，默认为 false，即在设备断开后不会再尝试重新连接
也可以在添加后再通过设备管理对象更新设备的连接策略
connectLocal的配置是内网自动连接，当设备内网连接断开后会尝试自动连接，仅需要某次连接时可添加后重新设置连接策略

4.2、设备同步

与设备添加类似，原配置默认为内网自动连接，v6.2版本更新默认为不进行内网自动连接，如果需要保留内网自动连接功能，请注意更新该配置。

XLinkAddDeviceTask task = XLinkAddDeviceTask.newBuilder()
        //是否在添加成功后进行内网连接，此处相当于设置内网连接策略为自动连接
        //默认为false，相当于不需要内网连接
        .setConnectLocal(true)
        ...
        .build();
XLinkSDK.startTask(task);

注：

原有的同步设备列表默认会进行内网的自动连接，v6.2版本同步设备列表之后将不再进行内网自动连接
connectLocal的配置是内网自动连接，当设备内网连接断开后会尝试自动连接，仅需要某次连接时可同步设备列表后重新设置连接策略

4.3、全局配置

若完全需要保留设备内网自动连接功能，可以直接在初始化时开启该功能，开启该功能后则将与此前版本的 XAPP SDK 处理策略一致，不管任何位置默认都是进行内网自动重连，除非再进行局部的配置。

XLinkConfig config = XLinkConfig.newBuilder()
        //全局开启默认进行内网自动重连配置
        .setLocalNetworkAutoConnection(true)
        ...
        .build();
XLinkAndroidSDK.init(config);

上次更新：2024-05-09