Android SDK开发指南

X-MQTT V6

资源名称	链接地址	版本号	发布时间	更新说明	文档链接
xlinksdk_v6	A-资源下载	v6.2.3.7	2018.09.20	新增 SDK 反初始化，重置方法新增支持的协议类型配置接口，优化数据通讯新增内网自动连接配置接口，默认不开启修正日志输出不转存到文件的情况下也允许输出到控制台优化扫描任务，提高扫描结果的准确率及发现速度优化扫描任务逻辑，提高扫描成功率优化扫描操作，默认不开启设备内网自动扫描连接修复订阅设备任务某些情况下不重试的问题，优化订阅任务流程新增订阅设备方式优化发送策略任务逻辑，修复任务某些情况下会尝试重试的问题修复设备云端连接失败时，云端状态已断开时依然重试的问题修复某些情况下云端断开时，未及时通知外部管理类状态变更的问题优化设备上下线状态消息通知，提高准确性及响应速度新增短信登录的 restful 接口，新增用户注销接口新增快捷登录任务,新增短信登录任务新增连接设备任务，新增连接策略优化数据缓存，断开连接时清除缓存信息修正描述性文本错误	A-快速开始、A-进阶篇、A-API、A-FAQ、A-v6.1.0.3版本升级到v6.2.3.7版本
xlink_sdk_demo	Android Demo	v6.1.0.12	2018.09.20	1.同步更新SDK版本到6.0.7.1

X-MQTT V5

资源名称	链接地址	版本号	发布时间	更新说明	文档链接
xlinksdk_v5	Android SDK (V5) 下载及更新说明	Full.5.0.5.1	2017-12-27	修复了部分情况下会导致扫描失败率较高的问题	Android SDK开发指南
xlink_sdk_demo	xlink_sdk_demo_full.5.0.5.1.zip（已含SDK库)demo_5.0.1.1_debug.apk	Full.5.0.1.1	2017-12-01	1、demo_apk 2、该APK为调试版本APK 3、demo默认为正式环境的API,若需要使用测试环境请使用源码重新编译 4、不同环境的账号无法互通,请注意 5、使用SDK版本为full_5.0.5.1

快速开始

在此部分主要是介绍如何最快速使用 XLINK APP SDK，包括了以下几部分内容：

• 下库与库配置
• API调用概述

通过以下的几个简单的步骤，就可以完成基础的设备连接并控制操作，然后就可以开始体验智能互联的力量了！

通过快速开始可快速了解 SDK 的基本流程与使用，通过[进阶篇](../Android SDK开发指南/A-进阶篇/A-Restful API使用.md)可详细了解 SDK 的核心功能及更多高级功能的使用，相关API使用请参考 [API](../Android SDK开发指南/A-API/A-API.md)，常见的问题解答请参考 [FAQ](../Android SDK开发指南/A-FAQ.md)

一、API调用概述

此章节主要从 XAPP SDK 的最简单的使用流程上介绍如何快速使用 XAPP SDK，包括了 XAPP SDK 最简单的初始化以及基本流程中常用的任务简单介绍与使用。

二、XAPP SDK简单初始化

XAPP SDK 初始化的参数有相对较多的可选参数，可以根据需要设置使用。这里介绍最简单的初始化过程（使用默认参数初始化使用）。

//使用默认参数初始化
XLinkConfig config = new XLinkConfig.Builder().build();
XLinkAndroidSDK.init(config);
 
//启动并运行SDK
XLinkSDK.start();
 
//停止当前SDK
XLinkSDK.stop();
//退出用户登录状态，清除用户信息，并停止当前SDK
XLinkSDK.logoutAndStop();

XAPP SDK 启动后即可进行相关功能使用。

三、基本流程任务使用

XAPP SDK 中提供了多个模块与功能，以下仅从最常见的使用流程进行基本介绍。最常见的使用流程为：

登录账号->扫描设备->添加订阅设备->设备控制->移除设备（->同步设备列表）

1、登录账号

登录账号使用XLinkUserAuthorizeTask，使用注册到的 APP 账号进行登录，该账号可通过 demo 注册进行获取；登录时需要 CropId，即企业ID，获取方式请参考资源准备

XLinkUserAuthorizeTask authTask = XLinkUserAuthorizeTask.newBuilder()
    //设置登录账号所属的企业ID
    .setCorpId("xxxx")
    //不管是手机还是邮箱登录，都可以设置上去，登录时并不区分是手机还是用邮箱
    .setPhone("13813813800", "123456")
    //如果需要设置手机区号则设置，默认为中国大陆手机区号+86，非中国手机号则需要设置
    .setPhoneZone("+86")
    .setEmail("test@xlink.cn","123456")
    .setListener(new TaskListXLinkTaskListnerener<UserAuthApi.UserAuthResponse>() {
            @Override
            public void onError(XLinkCoreException xLinkErrorCode) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(UserAuthApi.UserAuthResponse result) {
                //登录成功返回用户信息结果
            }
    })
    .build();
XLinkSDK.startTask(authTask);

2、扫描设备

扫描设备使用XLinkScanDeviceTask，扫描设备需要使用到设备的 ProductId，即产品ID，获取方式请参考资源准备

XLinkScanDeviceTask scanTask = XLinkScanDeviceTask.newBuilder()
        // 设置超时，单位毫秒，默认90秒, 建议使用60-90秒,根据需要可适当调整
        .setTotalTimeout(60000)
        //设置扫描的目标PID,可同时设置多个,不支持null与空字符串
        .setProductIds("xxx","xxx")
        //设备搜索回调
        .setScanDeviceListener(new XLinkScanDeviceListener() {
            @Override
            public void onScanResult(XDevice xDevice) {
                // 同一设备默认仅会回调一次
            }
 
            @Override
            public void onError(XLinkCoreException xLinkErrorCode) {
            }
 
            @Override
            public void onStart() {
            }
 
            @Override
            public void onComplete(Void aVoid) {
            }
        }).build();
XLinkSDK.startTask(scanTask);

3、添加订阅设备

添加订阅设备时会绑定当前用户与设备的关系，使用XLinkAddDeviceTask

XLinkAddDeviceTask addTask = XLinkAddDeviceTask.newBuilder()
        //设置需要添加的设置,一般来自扫描得到的设备对象
        .setXDevice(device)
        // 设置本次订阅任务的回调
        .setListener(new XLinkTaskListner<XDevice>() {
            @Override
            public void onError(XLinkCoreException xLinkErrorCode) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(XDevice xDevice) {
                //订阅成功返回设备对象
            }
        })
        .build();
XLinkSDK.startTask(addTask);

4、设备控制

设备控制分为两个操作，分别是获取数据端点和设置数据端点操作，两个操作分别对应了两个任务。其中数据端点的详细说明可查阅附录，此处可以先理解为获取设备的控制属性

• 获取数据端点

// 查询数据端点的值
XLinkGetDataPointTask getTask = XLinkGetDataPointTask.newBuilder()
        .setXDevice(xDevice)
        .setListener(new XLinkTaskListener<List<XLinkDataPoint>>() {
            @Override
            public void onError(XLinkCoreException e) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(List<XLinkDataPoint> xLinkDataPoints) {
                //返回获取到的数据端点
            }
        })
        .build();
XLinkSDK.startTask(getTask);

• 设置数据端点

//修改数据端点，控制设备
XLinkSetDataPointTask setTask = XLinkSetDataPointTask.newBuilder()
    .setXDevice(xDevice)
    .setDataPoints(dataPoints)
    .setListener(new XLinkTaskListener<XDevice>() {
        @Override
        public void onError(XLinkCoreException e) {
        }
         
        @Override
        public void onStart() {
        }
         
        @Override
        public void onComplete(XDevice xDevice) {
            //设置成功返回操作的设备对象
        }
    })
    .build();
XLinkSDK.startTask(setTask);

5、移除设备

移除设备会将设备删除掉并取消与用户的绑定关系，使用XLinkRemoveDeviceTask

XLinkRemoveDeviceTask removeTask = XLinkRemoveDeviceTask.newBuilder()
        //需要删除的设备,可以通过XLinkDeviceManager获取到对应的设备
        .setXDevice(device)
        .setListener(new XLinkTaskListener<String>() {
            @Override
            public void onError(XLinkCoreException e) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(String result) {
                //移除成功
            }
        }) 
        .build();
XLinkSDK.startTask(removeTask);

6、同步设备列表

在添加订阅成功设备之后，当前用户会与该设备存在绑定关系，在任何时候都可以从云端同步到该设备并进行设备的控制操作，使用XLinkSyncDeviceListTask

XLinkSyncDeviceListTask syncTask = XLinkSyncDeviceListTask.newBuilder()
        //同步设备后是否需要进行本地连接,默认为true
        .setConnectLocal(false)
        //设置同步设备的监听事件
        .setListener(new XLinkTaskListener<List<XDevice>>() {
            @Override
            public void onError(XLinkCoreException e) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(List<XDevice> devices) {
                //同步成功返回当前设备列表
            }
        })
        .build();
XLinkSDK.startTask(syncTask);

四、下载与库配置

此章节主要为 XAPP SDK 的下载相关说明及库使用时的配置信息说明。

1、下载

请从资源下载处下载 XAPP SDK 库文件

注意：请确保下载的压缩包解压后包括了以下的文件

• xlink_sdk.jar
• xlink_common.jar
• xlink_task_lib.jar
• xlink_wrapper.jar
• xlink_restful.jar
• expiringmap-0.5.7.jar

2、XAPP SDK 导入指引

1. 删除原来项目中引入libs文件夹下的所有前缀为 xlink_ 的jar(如果有引用旧文件)
2. 将刚下载的 XAPP SDK 压缩包解压缩，将得到的所有 jar 文件夹导入到你的项目中

注意：请务必删除掉所有旧文件再导入，详细原因说明请查看版本升级

下面是关于 jar 的简单说明：

jar 包	说明
xlink_sdk xlink_common xlink_task_lib	XAPP SDK 的核心功能实现
xlink_restful	XAPP SDK 所有相关的REST API实现,也包括了后台所有主要的API实现 推荐调用后台API时使用此JAR包
xlink_wrapper	XAPP SDK依赖于Android环境的中间件,也是 XAPP SDK 默认的初始化入口及一些默认实现类
expiringmap-0.5.7	第三方依赖库

3、库配置

XAPP SDK 引用库导入后，需要使用 gradle 进行一些配置工作，同时 mainfest 文件也需要进行一些权限配置。

注意： 1.旧版本的库配置与新版本有一些差异，如果从旧版本升级到新版本请参考版本升级-v5版本升级到v6.0.6.9版本 2.不同版本配置时有任何疑问请查看对应版本的版本升级

3.1、gradle 配置

XAPP SDK 中对一些第三方库有依赖关系，包括处理http请求的网络请求等，请根据确保添加以下依赖（依赖库版本可根据实际情况进行更新）

compile fileTree(include: ['*.jar'], dir: 'libs')
//网络请求库
compile 'com.squareup.retrofit2:retrofit:2.3.0'
compile 'com.squareup.retrofit2:converter-gson:2.3.0'
compile 'com.squareup.retrofit2:converter-scalars:2.3.0'
compile 'com.squareup.okhttp3:logging-interceptor:3.8.1'

3.2、manifest 权限与配置

mainifest文件的配置权限

<!--存储权限为日志文件需要,如果不需要提供日志的文件存储功能,也可以不提供此权限-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!--wIFI权限用于本地及云端状态切换及网络状态的检测需要-->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<!--网络权限用于云端连接的需要-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>

进阶篇

一、Restful API 使用

XAPP SDK 封装了部分常用的 Restful API，例如用户注册、登陆、找回密码等等。完整的 Restful API 文档在：OPEN-API开发指南

1、使用方式

用户通过如下方式可调用 Restful API:

//获取应用接口API
XLinkRestful.getApplicationApi().*****

用户调用其提供的方法即可，例如：

// 用户登陆
UserAuthApi.UserAuthRequest request = new UserAuthApi.UserAuthRequest();
request.corp_id = mCorpId;
request.email = mEmail;
request.phone = mPhone;
request.password = mPwd;
XLinkRestful.getApplicationApi().authorizeUser(request)...

XAPP SDK 使用 retrofit2 作为HTTP请求库，使用方法请参考官方文档：http://square.github.io/retrofit/

2、自定义 Restful

若 XAPP SDK 自带 Restful API 接口不能满足需求，开发者需自己实现，可通过如下方式：

2.1、使用 client 处理接口

在使用 OkHttpClient 时，如果对Client的自定义要求不高，并且直接使用 XAPP SDK 调用 Restful 接口时，可以通过在 XAPP SDK 中设置setNetworkClientProcessor()在 XAPP SDK 首次创建 Client 时进行自定义处理

XLinkConfig config = XLinkConfig.newBuilder()
        .setNetworkClientProcessor(new NetworkClientProcessor() {
            @Override
            public void processorClient(OkHttpClient.Builder builder) {
                //自定义Client的处理操作，如SSL的配置等
            }
        })
        .build()

2.2、其它方式实现 API 接口

若开发者使用其他方式（非 retrofit2）实现 API 接口，要注意 AccessToken 必须从 XAPP SDK 取出，即当开发者调用需要 accessToken 的接口时，必须使用 XLinkUserManager.getInstance().getAccessToken() 返回的 accessToken ，并且注意不要缓存起来使用

当外部进行了其它的登录操作将导致 XAPP SDK 中维护的 accessToken 过期，此时将会导致 XAPP SDK 的一些功能是不正常或者不可用的，并可能导致 XAPP SDK 通知用户退出事件，同时清除当前缓存的所有数据

注意：accessToken 应该从 XAPP SDK 中随取随用，不要进行缓存，accessToken 的维护工作应该交由 XAPP SDK 进行

2.3、使用OkHttpClient

若以上方法都不适用，也可以从 XLinkRestful 中获取到当前使用的 httpClient 并进行调整，示例代码如下：

//定义新的接口
interface ApiService {
    @Headers({"Content-Type: application/json"})
    @POST("/{user_id}/xxx/xxx/xxx")
    Call<String> postApi(@Query("user_id") String userId, @Body List<Request> request);
 
    class Request {
        public String params;
    }
}
 
//sdk需要初始化操作
XLinkConfig config=...;
XLinkAndroidSDK.init(config);
 
//使用XLinkRestful对象的 httpClient 创建自定义的retrofit
Retrofit retrofit = new Retrofit.Builder()
        //使用XLinkRestful中的基础url
        .baseUrl(XLinkRestful.getBaseRetrofit().baseUrl())
        //使用XLinkRestful中创建的client
        .client(XLinkRestful.getApiHttpClient().newBuilder().build())
        //如果返回数据为空，建议添加到这个转换器，并且请保持在第一个添加的位置
        .addConverterFactory(ScalarsConverterFactory.create())
        .addConverterFactory(GsonConverterFactory.create())
        .build();
//创建ApiService并调用接口
ApiService api=retrofit.create(ApiService.class);
api.postApi(request)
    .enqueue(...);

注意：XLinkRestful 必须在正常初始化成功之后才会创建 client。若未进行初始化时，获取 client 会抛出未初始化的异常。可通过XLinkRestful.isInitialized()判断是否已初始化

二、XAPP SDK 基本配置

程序运行前要配置 XAPP SDK config 配置信息，之后调用XLinkSDK.start()后生效。前面快速开始时已经介绍了最简单的配置方式，此部分将具体地介绍一些常用的配置。

XAPP SDK 支持以下功能配置：

• 调试日志输出功能
• API 域名配置（API 环境切换）
• CM服务器连接版本（自v6.2.6.x版本起）
• 全局的数据通讯策略
• 全局的回调监听

XLinkConfig.Builder builder = new XLinkConfig.Builder()
        //设置输出日志配置信息
        .setLogConfig(XLinkAndroidSDK.defaultLogConfig(context))
        //设置API服务器地址与端口,默认值为正式环境: https://api2.xlink.cn,443
        .setApiServer(hostApi, portApi)
        //设置CM服务器地址与端口,默认值为正式环境: mqtt.xlink.cn,1884
        .setCloudServer(hostCM, portCM)；
        //SSL目前仅对CM连接有效,测试环境时需要开启SSL false
        .setEnableSSL(ssl)
        //设置数据默认发送策略
        .setSendDataPolicy(sendPolicy)
        //是否打印部分日志
        .setDebug(true)
        //设置云端回调监听
        .setXLinkCloudListener(xlinkListener)
        //设置用户登录回调监听
        .setUserListener(xlinkListener)
        //设置数据回调监听
        .setDataListener(xlinkListener)
        //设置物模型回调监听
        .setTMLAttributeListener(xlinkListener)
        //设置设备状态监听
        .setDeviceStateListener(xlinkListener);

1、 调试日志输出功能

XAPP SDK 的日志输出功能必须设置才能正常使用，否则无法正常输出到控制台查看，XAPP SDK 已提供了默认的日志输出实现，默认日志配置如下：

• 将输出日志到控制台
• 将日志信息保存到日志文件中
• 日志文件保存默认位置：/sdcard/xlink/包名_log_时间.txt

注意事项：自v6.2.6.x版本起，默认情况下日志文件保存的位置为 /sdcard/xlink/包名/log_时间.txt

默认的日志输出配置仅需要一句代码，若无法正常输出日志，请确认是否开启了存储权限，若有其它问题可参考 FAQ

XLinkConfig config = new XLinkConfig.Builder()
        ...
        .setLogConfig(XLinkAndroidSDK.defaultLogConfig(context))
        ...

注意事项：日志配置允许进行自定义配置，默认配置可以满足大部分情况下的要求，如果需要更改日志文件保存路径或者是自定义配置信息，请查看进阶使用说明。

2、API域名配置

API 域名默认是使用正式环境的 API 域名配置，配置选项列表说明如下：

配置名称	含义	默认值
setCloudServer(String, int)	设置 CM 服务器	mqtt.xlink.cn,1884
setApiServer(String, int)	设置 HTTP API 服务器	https://api2.xlink.cn, 443
setEnableSSL(Boolean)	是否使用 SSL	true

其中关于 API 及 CM 服务器是包括了 XLink 正式环境与测试环境的地址，当然也允许配置成私有云地址；以下为不同环境下的地址信息:

环境	域名	端口	启用SSL(仅公有云)
XLink 公有云正式环境 API	https://api2.xlink.cn	443
XLink 公有云正式环境 CM	mqtt.xlink.cn	1884	true
XLink 公有云正式环境 CM	mqtt.xlink.cn	1883	false（无SSL）
XLink 公有云测试环境 API	http://dev-api.xlink.cn	80
XLink 公有云测试环境 CM	dev-cm.xlink.cn	1884	true
XLink 公有云测试环境 CM	dev-cm.xlink.cn	1883	false（无SSL）

注意：

1. 不进行服务器地址配置的情况下，默认使用正式环境信息
2. 公有云同时支持 SSL 端口及非 SSL 端口，默认情况下使用 SSL 端口，建议使用此端口；确认不需要进行启用 SSL 时可使用1883端口

3、 CM服务器连接版本（自v6.2.x版本起）

由于v6.2版本的功能更新（详情请查看版本升级 md)中v6.2相关升级说明），CM 服务器版本也同步更新。 目前公有云已更新到版本3，部分企业环境的 CM 服务器版本可能未进行更新，依然需要使用旧版本连接。

自v6.2版本以后 XAPP SDK 默认使用版本3进行 CM 服务器的连接，可通过以下配置变更连接版本。

XLinkConfig.Builder builder = XLinkConfig.newBuilder()
        //默认使用版本为3，可切换为2版本
        .setMQTTClientVersion(2)
        ...
        .build

注意事项：CM 服务器版本并不是高版本必然优于低版本，主要的版本变更是由于新功能的支持，所有原有功能和基础功能都是正常可用的，当不需要使用提供的新功能不需要升级。

4、全局的数据通讯策略

物联云平台采用数据端点来描述物理设备的状态和能力

• 可通过设备状况的查询和回调接口来获取设备的实时状态
• 可通过更新数据端点状态的接口来实现设备的远程控制

XAPP SDK 与设备连接有不同的情况，包括以下三种情况：

• 通过云平台与设备连接，后续简称为：云端连接
• 通过内网（局域网）与设备连接，后续简称为：内网连接
• 同时存在云端连接与内网连接

XAPP SDK 支持指定内网的局域网连接或外网的云端连接来发送数据，也可以采用 AUTO 模式由 XAPP SDK 底层自适应内外的数据通讯。数据发送的策略有如下几种：

发送策略	说明
AUTO	默认值，自动选择发送数据的通道(内/外网)，选择的依据是当前通道的 RTT，RTT 低的通道会被选中
LOCAL_ONLY	只尝试从内网发送
LOCAL_FIRST	尝试从内网发送，失败则尝试外网发送
CLOUD_ONLY	只尝试从外网发送
CLOUD_FIRST	尝试从外网发送，失败则尝试内网发送

在初始化 XAPP SDK 时可以设置全局使用的数据通讯策略：

XLinkConfig config = new XLinkConfig.Builder()
        ...
        .setSendDataPolicy(XLinkSendDataPolicy.CLOUD_ONLY)
        ...

5、全局的回调监听

XAPP SDK 提供了常用接口的全局回调，包括了以下几种回调

• XLinkCloudListener-云端回调，XAPP SDK 与云平台连接的状态回调及所有来自云端的消息推送
• XLinkUserListener-用户状态回调，XAPP SDK 维护的用户状态回调，涉及用户退出、授权信息过期、踢出等状态
• XLinkDataListener-数据回调，XAPP SDK 接收到数据端点变更的通知回调
• XLinkDeviceStateListener-设备状态回调，XAPP SDK 维护的设备状态变更时的通知回调
• XLinkDeviceEventListener-设备事件通知回调，XAPP SDK 维护的设备发送事件到 XAPP SDK 时的通知回调

这部分的监听回调都在全局配置时添加的，一般情况下是在应用对象中（Application）中统一进行监听和处理

5.1、XLinkCloudListener-云端回调

云端回调包括 XAPP SDK 连接到 CM 云端服务器的连接状态回调,以及所有来自云端的消息推送

// 云端回调
configBuilder.setCloudListener(new XLinkCloudListener() {
    @override
    public void onCloudStateChanged(CloudConnectionState state) {
        // 当SDK与云平台连上/断开的时候，会回调这个方法
        // 根据 state 状态可判断连接状态为断开/连接中/已连接
    }
 
    @Override
    public void onEventNotify(EventNotify eventNotify) {
        // 当SDK连接上云端，并接收到云端推送时，会回调这个方法。
    }
});

事件的详细介绍说明请查看进阶篇-云端消息推送

5.2、XLinkUserListener-用户状态回调

用户登录状态的回调，在用户账号退出时，会通过此回调进行用户退出账号原因的通知

//用户信息回调
configBuilder.setUserListener(new XLinkUserListener() {
    @Override
    public void onUserLogout(LogoutReason reason) {
        // 用户被下线（被踢或者手动退出）/授权信息过期 的时候，会回调这个方法。
        // 请根据LogoutReason进行处理
    }
});

用户退出原因有三种：

原因	说明
USER_LOGOUT	用户主动退出，一般情况下由于调用XLinkSDK.logoutAndStop()引起的
SINGLE_SIGN_KICK_OFF	用户账号由于被其它人登录导致了当前账号被踢出的
TOKEN_EXPIRED	用户凭证过期

通常情况下，SINGLE_SIGN_KICK_OFF与TOKEN_EXPIRED都是需要用户重新登录的，一般发生时也建议调用XLinkSDK.logoutAndStop()停止当前 XAPP SDK

用户退出原因及授权信息处理详细说明请查看进阶篇-用户授权管理

5.3、XLinkDataListener-数据回调

数据回调时目前最主要的是数据端点的变更通知回调。设备的数据端点变更时，当设备进行上报后会通过回调通知到 APP 数据端点的更新。

// 数据回调
configBuilder.setDataListener(new XLinkDataListener() {
    @Override
    public void onDataPointUpdate(XDevice xDevice, List<XLinkDataPoint> list) {
        // 当SDK收到设备上报的数据端点时，会回调这个方法。
    }
});

数据端点相关说明请查看进阶篇-数据端点详解

5.4、XLinkDeviceStateListener-设备状态回调

设备状态回调在设备状态发生变更时会进行回调，请注意并非所有的设备都会在此回调接口中进行回调，有且仅有存在设备维护列表中的设备状态发生改变时才会通知此回调通知，关于“维护列表设备”的详细说明可参考 进阶篇-设备连接状态管理

设备状态回调的注意点：

1. 通过XLinkSyncDeviceListTask同步列表操作任务进行设备同步后，默认都会添加到维护列表中
2. 通过XLinkAddDeviceTask添加设备任务添加的设备也会添加到设备维护列表中
3. 通过XLinkSyncHomeDeviceListTask同步Home中设备列表任务进行设备同步后，默认都会添加到维护列表中

// 设备状态回调
configBuilder.setDeviceStateListener(new XLinkDeviceStateListener() {
    @Override
    public void onDeviceStateChanged(XDevice xDevice, XDevice.State state) {
        // 受SDK管理的设备状态发生改变时,一般情况下同步下来已订阅过的设备都会在维护列表中
    }
     
    @Override
    public void onDeviceChanged(XDevice xDevice, XDevice.Event event){
        // 设备属性或者设备状态发生改变时，会回调这个方法。
        // 详情请参阅XDevice.Event
    }
});

5.5、 XLinkDeviceEventListener-设备事件通知回调（自v6.2.x版本起）

当设备发送事件给 XAPP SDK 时，XAPP SDK 接收到事件后将会通过此回调通知用户。请参考 API-XLinkDeviceEvent

configBuilder.setEventListener(new XLinkDeviceEventListener(){
        @Override
        public void onDeviceEventNotify(@NotNull XDevice device, @NotNull List<XLinkDeviceEvent> event, int from) {
            //接收到来自设备的事件时将会回调此方法，from为事件来自内网或者是云端的标识
        }
})

• from

值	说明
XLinkConstant.FROM_LOCAL	来自内网事件
XLinkConstant.FROM_CLOUD	来自云端事件

6、 XAPP SDK 启动与停止

注意以上为 XAPP SDK 初始化的一些基础配置，XAPP SDK 需要在启动后才能正常使用

// 启动SDK
XLinkSDK.start();
不使用SDK时，可调用stop()。
 
// 停止SDK, 断开云端连接，回收资源
XLinkSDK.stop();
 
当App退出登录（授权失败或其他原因需要重新授权的情况）时，可调用XLinkSDK.logoutAndStop()
 
 
// 停止SDK, 断开云端连接，回收资源，清除授权信息。
//请注意此处会停止当前的SDK,如果需要再次使用必须再次start SDK
XLinkSDK.logoutAndStop();

注：

1. 任何时候使用XLinkSDK.stop()方法都会导致 XAPP SDK 的中止，而一旦 XAPP SDK 中止后，就不会再与设备保持任何通讯
2. 在任何一次XLinkSDK.stop() 之后需要使用 XAPP SDK 的话，请务必调用 XLinkSDK.start() 操作

三、XAPP SDK高级配置

在入门篇中介绍了最常见的一些配置和默认的一些配置使用，XAPP SDK 还支持了其它一些复杂的配置方式，大多数情况下默认配置是能满足需要的。

但是某些情况下可能要求更多自定义配置，以下为 XAPP SDK 中提供的一些自定义配置。

1、 调试日志高级设置

对于调试日志，如果不想使用默认的 Log 配置，可以自行调整 Log 配置。

BaseLog.Config logConfig = new BaseLog.Config()
        //log输出日志路径,请注意现在android并不推荐直接使用 /sdcard 的路径
        .setLogoutPath("/sdcard/xlink")
        //输出日志等级
        .setDebugLevel(Loggable.DEBUG)
        //存储文件日志等级(一般请使用DEBUG)
        .setBufferLevel(Loggable.DEBUG)
        //是否允许将日志存储到文件中
        .setEnableLogFile(true)
        //存储日志文件的前缀
        .setLogPreFix("main")
        .setLoggable(new Loggable() {
            @Override
            public int log(int level, String tag, String msg, Throwable e) {
                //可根据使用的log输出方式输出日志,如:
                System.out.println(BaseLog.getPrintLogMsg(tag, msg));
                return level;
            }
        });

默认使用的日志配置XLinkAndroidSDK.defaultConfig(context)也是用同样的方式创建了一个 APP 专用的日志配置信息。

若想基于默认使用的日志配置信息进行少量的更新，只需要直接在默认配置上更新相关配置即可。

BaseLog.Config logConfig = XLinkAndroidSDK.defaultConfig(context)
        .setDebugLevel(Loggable.ERROR)
        .setLogPreFix("rename");

** 注意：自定义实现 LogConfig 时，需要配置setLoggable()，默认不会使用 logcat 输出日志到控制台**

1.1、日志配置变更——自v6.2.6.x版本起

对于调试的日志输出配置，更新了日志的输出配置方式。旧的日志输出配置方式依然有效，但是如果设置了新的配置方式，则将使用新的参数进行处理，旧的配置参数将被忽略。

BaseLog.Config config = new BaseLog.Config()
        //设置是否输出日志到文件中保存
        .setEnableLogFile(true)
        //设置日志输出等级
        .setDebugLevel(Loggable.DEBUG)
        //设置日志输出到文件中的等级
        .setBufferLevel(Loggable.DEBUG)
        //设置自定义的日志输出对象
        .setLoggable(customLogger)
        //设置新的日志信息配置
        .setLogInfoProvider(new LogInfoProvider() {
            @NonNull
            @Override
            public String provideLogFilesStoragePath() {
                //提供日志文件保存文件夹路径，注意只是文件夹，不是文件
                return Environment.getExternalStorageDirectory().getPath().concat("/xlink/");
            }
            @NonNull
            @Override
            public String provideLogFileName(String time) {
                //当一个日志文件生成时，会调用此方法，参数为文件生成的时间信息；
                //生成一个日志文件名并返回，建议使用上时间信息，防止文件名重复；
                //重名文件不会替换旧文件
                return "log_" + time;
            }
            @NonNull
            @Override
            public String provideLogZipFileName(String time) {
                //若日志文件夹中存在大量日志文件时，将会进行压缩；创建压缩文件时将调用此方法，生成压缩文件的名称
                return "archive_" + time;
            }
        });

默认情况下，如果没有特殊要求或者是特殊处理，建议使用XLinkAndroidSDK提供的默认日志配置参数，也可以在该默认参数中进行修改。

//使用默认配置参数，或者是基于默认参数进行局部修改
BaseLog.Config config=XLinkAndroidSDK.defaultLogConfig(this)
        .setEnableLogFile(false);
//初始化SDK
XLinkConfig.Builder builder = new XLinkConfig.Builder()
        .setLogConfig(config)
        ...

在默认日志配置参数中，相对以前的变更主要在于：

1. 生成的日志文件不再全部置于/sdcard/xlink的文件夹下，将会根据当前应用包名创建文件夹，并且置于相应的包名文件夹下/sdcard/xlink/包名
2. 允许开发者自行定义日志文件名称及压缩文件名称，以便定时对日志进行清理或移除
3. 现在可以获取到当前正在运行的 SDK 输出的日志文件路径

//此方法仅在 XLog 已经启用并且存在输出日志的情况下才可用；否则将返回 null 或不正确的路径
if (XLog.isInited() && XLog.getInstance().isStarted()) {
    String logFilePath = XLog.getInstance().getCurrentLogFilePath();
}

注意事项：务必调用XLog.isInited()确认 XLog 是否 已经初始化成功，否则可能获取到错误的路径；日志文件只有在XLog.startLog()之后才会创建，所以也需要确认 XLog 是否已经启动成功。

2、崩溃日志配置

XAPP SDK 默认支持收集崩溃日志并保存到文件中，该功能默认不开启。

崩溃日志默认保存到以下位置：/sdcard/xlink/crash/包名_时间_crash.txt

XLinkConfig.Builder builder = new XLinkConfig.Builder()
        ...
        //是否自动转存崩溃日志
        .setAutoDumpCrash(true)
        //设置崩溃日志的存储信息,若需要转存崩溃日志,请务必设置此参数
        .setCrashInfoProviderable(new XLinkCrashInfoProvider(this))
        ...
        .build();

** 注意：设置保存崩溃日志时,请务必设置崩溃日志存储信息setCrashInfoProviderable()，否则无法将抛出异常，XAPP SDK 无法默认收集应用的崩溃信息**

2.1、自定义保存路径

默认崩溃日志的保存路径，优化保存到外部存储介质中，无法保存时将保存到当前包内部文件夹下。

某些情况下可能无法准确保存到有效的文件位置，通过对默认崩溃日志信息进行少量修改即可将崩溃日志文件保存到指定路径下。

XLinkCrashInfoProvider提供了三个构造方法用于不同的路径配置，默认情况下会收集当前移动设备的一些基本信息(包括 Android 版本与机型等)

//默认使用sdcard,存储子路径为/xlink/crash
new XLinkCrashInfoProvider(context);
//默认使用sdcard,存储子路径为/package
new XLinkCrashInfoProvider(context,"/package");
//由绝对存储路径决定存储位置
new XLinkCrashInfoProvider(context.getPackageName(),"/absolutely_path");

2.2、自定义崩溃信息收集类

如果不想使用默认的 CrashInfoProvider，或者需要收集一些特殊的信息，可以自行实现该接口处理 crash 信息

CrashInfoProviderable carshProvider = new CrashInfoProviderable() {
    @Override
    public String provideEnvironment() {
        //提供当前运行环境
        //dumpDeviceRomInfo为默认提供的方法，可收集Android系统相关的基本信息
        return XLinkCrashInfoProvider.dumpDeviceRomInfo();
    }
    @Override
    public String provideCrashFileStoragePath() {
        //crash文件保存路径,请注意现在android并不推荐直接使用 /sdcard 的路径
        return "/sdcard/xlink/crash/";
    }
    @Override
    public String provideCrashFileName(String s) {
        //以文件创建时间为fileName,需要添加任何前缀或者更改文件名请自行处理,默认会添加后缀txt
        return DemoApplication.getAppInstance().getPackageName()
                .concat(s)
                .concat("_crash");
    }

** 注意：如果需要自行收集崩溃信息或者是使用第三方崩溃收集工具（如Buggly），则不推荐开启崩溃日志收集功能，可能会导致崩溃信息无法正常收集**

3、用户快捷登录

详情请查看进阶篇-用户授权管理

4、多点登录

多点登录是针对对于同一账号可能在不同场景中使用时，不希望账号之前发生互踢现象而新增的一个功能。如同时允许在 pad 及手机上登录同一账号。

使用多点登录时，需要指定多点登录的登录源，当不存在登录源信息时，默认为同一基本用户。当存在登录源信息时，在相同账号登录时会依赖登录源进行识别，以判断是否允许同一账号同时处于登录可用状态。

XLinkConfig config = XLinkConfig.newBuilder()
    //设置登录源,单点登录时可以不进行设置,不同登录源允许多点登录
    .setAuthResource(resource)
    ...
    .build();
XLinkAndroidSDK.init(config);

不同登录对账号的登录状态影响如下:

登录状态1	登录状态2	是否允许同时登录
登录状态1	登录状态2	是否允许同时登录
默认登录源+账号	默认登录源+账号	不允许
默认登录源+账号	其它登录源+账号	允许
登录源1+账号	登录源1+账号	不允许(同账号且同一登录源)
登录源1+账号	登录源2+账号	允许(同账号但不同登录源)

注意：登陆源只支持数字和字母（暂不支持空格），最大长度为16个字符，默认为 null

5、Restful 接口 client 配置

REST 接口是使用 retrofit 进行网络请求， 部分 API 请求可能需要进行 SSL 的证书配置，此时需要通过 okHttpClient 配置相应的 SSL 证书。

原有的 REST 接口并不存在相关的 SSL 配置处理，所以新版本提供了 REST 接口对 client 进行自定义配置的接口

builder.setNetworkClientProcessor(new NetworkClientProcessor() {
    @Override
    public void processorClient(OkHttpClient.Builder builder) {
        //根据需要使用可自定义对 client 进行配置
        builder.sslSocketFactory(factory,manager);
    }
});

** 注意：该配置的 client 将会被整个 XAPP SDK 使用过程中使用到**

6、CM 连接 SSL 配置

部分情况下可能需要使用到企业的自签证书，此时默认的 SSL 处理将不能正常提供有效的校验及数据通行处理，新增了可自定义提供 CM 连接时的 SSL socket 对象

builder.setSSLFactoryProvider(new SSLFactoryProviderable() {
    @Override
    public SocketFactory getSSLFactory() {
        //根据需要创建自己的SSL socket提供证书的验证操作
        return null;
    }
});

四、基础功能使用

所有 XAPP SDK 的功能都是通过任务实现的，任务的使用是 XAPP SDK 的核心。

1、任务调用通用准则

XAPP SDK 的任务创建基本都是以 Builder 的形式进行创建，然后通过 startTask() 操作执行任务，取消任务可以通过 stopTask() 进行中止

//创建任务
Task task=***Task.newBuilder()
    .setListener(listener)
    .build();
//执行任务(异步)
XLinkSDk.startTask(task);
//中止任务
XLinkSDK.stopTask(task);
//或者取消直接对任务进行取消
task.cancel();

在任务回调中，任务回调只要是TaskListener类型的接口都是允许的，该接口有四个抽象方法需要实现。

//任务执行错误（result.error != null）回调。注意此回调在task.onRetry()返回false后才会回调
void onError(Task<T> task, Throwable error);
 
//任务开始执行回调
void onStart(Task<T> task);
 
//任务重试时的回调
void onRetry(Task<T> task, T result);
 
//任务执行成功回调
void onComplete(Task<T> task, T result);

一般情况下建议直接使用XLinkTaskListener抽象类，该类会将结果回调到主线程而不需要进行线程的切换工作。

//使用XLinkTaskListener时回调会在主线程中执行
Task task = ***Task.newBuilder()
        .setListener(new XLinkTaskListener<T>{
            @Override
            public void onError(XLinkCoreException ex) {}
             
             @Override
            public void onStart() {}
             
            @Override
            public void onComplete(T result) {}
        })

实际使用场景 中onStart()与onRetry()的使用频率比较低，所以也可以使用此接口的空实现类TaskListenerAdapter直接仅重写需要的方法。

2、XAPP SDK用户授权登录

启动 XAPP SDK 后，若要使用云端服务相关操作（获取设备列表、通过云端获取数据端点、添加设备、删除设备等），需进行用户授权。其中用户授权分两种：

• 普通账号登录，即直接通过注册到物联云平台后台管理系统或者是部署私有云后注册使用的用户
• 第三方登录，包括但不限 QQ、微信等

不管通过哪种方式进行授权，最终都会获取到一些用户授权信息，建议开发者可以保存此部分信息以备用（根据实际的使用需求有可能不需要使用到，不需要使用时可以不保存）

2.1、普通账号授权

对于从平台注册的账号，需要使用普通账号授权任务进行登录操作并获取到授权信息。

XLinkUserAuthorizeTask task = XLinkUserAuthorizeTask.newBuilder()
            // 手机号和密码
            .setPhone(phone, password)
            //邮箱和密码，setPhone和setEmail并没有实际的账号类型,都设置是允许的
            .setEmail(email, password)
            //企业ID
            .setCorpId(corpId)
            .setListener(new XLinkTaskListener<UserAuthApi.UserAuthResponse>() {
                @Override
                public void onError(XLinkCoreException xLinkErrorCode{
                    // 登录失败
                }
 
                @Override
                public void onStart() {
                }
 
                @Override
                public void onComplete(UserAuthApi.UserAuthResponse result) {
                    // 登录成功，在result中含有授权信息
                    // SDK内部自动进行云端连接
                }
            })
            .build();

2.2、第三方账号授权

第三账号授权任务一般是第三方账号接入云平台时的用户账号，该部分账号需要通过第三方账号登录授权任务登录，需要提供第三方账号相关的 openId、accessToken 和其它信息

XLinkThirdPartyAuthorizeTask task = XLinkThirdPartyAuthorizeTask.newBuilder()
            // 第三方授权后获取的openId和accessToken
            .setOpenId(openId)
            .setAccessToken(accessToken)
            //企业ID
            .setCorpId(corpId)
            //登录源,来源类型有以下几种
            .setSource(XLinkRestfulEnum.UserSource.WEIXIN)
            .setListener(new XLinkTaskListener<ThirdPartyAuthApi.AuthResponse>() {
                @Override
                public void onComplete(ThirdPartyAuthApi.AuthResponse result) {
                    // 登录成功，在result中含有授权信息
                    // SDK内部自动进行云端连接
                }
            })
            .build();

登录源,来源类型有以下几种

登录源	类型
网页	XLinkRestfulEnum.UserSource.WEB
Android	XLinkRestfulEnum.UserSource.ANDROID
IOS	XLinkRestfulEnum.UserSource.IOS
微信	XLinkRestfulEnum.UserSource.WEIXIN
QQ	XLinkRestfulEnum.UserSource.QQ
微博	XLinkRestfulEnum.UserSource.WEIBO
Facebook	XLinkRestfulEnum.UserSource.FACEBOOK
twitter	XLinkRestfulEnum.UserSource.TWITTER
其它来源	XLinkRestfulEnum.UserSource.OTHER

注意：由于 XAPP SDK 内部需要授权信息，请使用 XAPP SDK 提供的授权接口进行授权，不要自行通过 Restful 进行用户授权

2.3、手机短信登录授权

手机短信登录授权是方便用户通过手机接收验证码快速登录的功能，并且 SDK 在用户登录成功后将使用用户信息自行进行云端连接操作。推荐需要实现短信登录功能时，直接使用此任务。

• 获取手机短信验证码

XLinkThirdPartyAuthorizeTask task = XLinkThirdPartyAuthorizeTask.newBuilder()
            // 第三方授权后获取的openId和accessToken
            .setOpenId(openId)
            .setAccessToken(accessToken)
            //企业ID
            .setCorpId(corpId)
            //登录源,来源类型有以下几种
            .setSource(XLinkRestfulEnum.UserSource.WEIXIN)
            .setListener(new XLinkTaskListener<ThirdPartyAuthApi.AuthResponse>() {
                @Override
                public void onComplete(ThirdPartyAuthApi.AuthResponse result) {
                    // 登录成功，在result中含有授权信息
                    // SDK内部自动进行云端连接
                }
            })
            .build();

• 通过短信登录任务进行登录

XLinkSmsAuthorizeTask task = XLinkSmsAuthorizeTask.newBuilder()
        .setCorpId(corpId)
        .setPhone(phone)
        //设置手机的区号，默认为+86中国大陆，可选参数
        .setPhoneZone(phoneZone)
        //手机验证码
        .setVerifyCode(captcha)
        .setListener(new XLinkTaskListener<UserAuthApi.UserSmsAuthResponse>() {
            @Override
            public void onComplete(UserAuthApi.UserSmsAuthResponse result) {
                // 登录成功，在result中含有授权信息
                // SDK内部自动进行云端连接
            }
        })
        .build();
XLinkSDK.startTask(task);

** 注意：获取手机短信登录验证码的接口依然需要通过 XLinkRestful 调用**

3、设备操作

除了用户登录操作，XAPP SDK 中最重要的就是与设备通讯的任务了。一般情况下会包含以下几个任务：

任务名称	任务意义	任务作用
XLinkScanDeviceTask	扫描设备任务	扫描同一局域网内的设备以便后续添加订阅和连接
XLinkAddDeviceTask	添加订阅设备任务	添加设备，并将设备与用户关联绑定关系，实现任何情况下用户可同步并使用设备
XLinkSyncDeviceListTask	同步设备任务	同步与用户关联的设备列表信息
XLinkRemoveDeviceTask	移除设备任务	移除设备并取消用户与设备之前的关联关系
XLinkGetDataPointTask	获取设备数据端点任务	获取设备数据的任务
XLinkSetDataPointTask	设置设备数据端点任务	设置设备数据的任务

3.1、扫描设备任务

对于一个全新的设备，需要通过扫描局域网内的设备发现设备，再进行后续的操作。这是设备操作的首要步骤。

XLinkScanDeviceTask scanTask = XLinkScanDeviceTask.newBuilder()
        // 设置超时，单位毫秒，根据需要可适当调整
        .setTotalTimeout(45000)
        //设置扫描的目标PID,可同时设置多个,不支持null与空字符串
        .setProductIds(pid1,pid2)
        //设置搜索回调,回调在主线程上执行
        .setScanDeviceListener(new XLinkScanDeviceListener() {
             @Override
             public void onScanResult(XDevice xDevice) {
                 // 同一设备仅会回调一次
             }
 
             @Override
             public void onError(XLinkCoreException xLinkErrorCode) {
             }
 
             @Override
             public void onStart() {
             }
 
             @Override
             public void onComplete(Void aVoid) {
             }
         }).build();

** 扫描设备操作仅通过setScanDeviceListener设置扫描回调，不需要设置setListener**

注意：扫描设备时需要一些条件限制，请务必确认处于相应环境下才能正常扫描到设备

• APP 与扫描的设备必须在同一局域网中
• 确认设备版本与 APP 支持的版本兼容

注意事项：若扫描不到设备并无法确认原因，可查看 [FAQ](../Android SDK开发指南/A-FAQ.md) 相关问题解答

3.2、添加订阅设备

添加设备是通过内网与设备通过后，再将校验信息提交到云端，通过云端的校验后将设备与用户形成绑定关系。成功订阅过的设备将在同步设备列表时可以同步到。

XLinkAddDeviceTask task = XLinkAddDeviceTask.newBuilder()
        //设置需要添加的设置,一般来自扫描得到的设备对象
        .setXDevice(device)
        //是否在添加成功后进行设备内网连接
        .setConnectLocal(true)
        //是否在添加成功后订阅设备
        .setNeedSubscription(true)
        //设置本次订阅任务的回调
        .setListener(xxxx)
        .build();

注意事项：已添加成功的设备，XAPP SDK 会自动在云端建立当前用户账号与设备的订阅关系，并用于后续的数据更新和同步，具体请参考下文的“同步设备”。

关于添加与订阅的差异如下:

操作	说明	影响
添加设备	添加设备为 XAPP SDK 与设备之前建立起联系并从设备获取到部分设备信息(可用于校验工作)	添加是正常情况下使用设备的前提条件，但是添加操作与云端及用户无直接关联
订阅设备	通过云端提交设备信息,云端在校验成功后将设备与当前用户绑定关系	订阅是保存用户与设备之间关系的必要操作，只有订阅后的设备才能进行远程同步及控制

注：默认情况下，XLinkAddDeviceTask任务是包括了添加设备及订阅设备两部分操作。

3.3、同步设备任务

同步设备任务用于将将当前用户的设备设备从云端同步到内网。任务完成后默认自动发起内网连接和云端连接, 同步后的设备会自动添加到设备维护列表中进行维护，设备状态变更时也会有相应的状态回调。

XLinkSyncDeviceListTask task = XLinkSyncDeviceListTask.newBuilder()
        //同步设备后是否需要进行内网连接,默认为true,v6.2版本起默认为false
        .setConnectLocal(false)
        //设置同步设备的监听事件
        .setListener(xxx)
        .build();

同步设备要求设备和当前用户之间有订阅关系，无订阅关系无法同步到设备。若设备与 APP 在同一局域网，一般建议设置启用内网连接 setConnectLocal(true) 。完全不需要依赖内网通讯的，建议关闭内网连接setConnectLocal(false)，以减少部分资源的维护成本与性能消耗。

3.4、移除设备

移除设备成功时，XAPP SDK 会自动从云端解除当前用户与设备之间的订阅关系，并删除与该设备相关的共享和访问权限, 同时也会将该设备移除维护列表, 设备将不能再使用。

XLinkRemoveDeviceTask removeDeviceTask = XLinkRemoveDeviceTask.newBuilder()
        //需要删除的设备,可以通过XLinkDeviceManager获取到对应的设备
        .setXDevice(device)
        .setListener(xxx)  
        .build();

3.5、获取设备物模型

对设备的控制实际上就是对设备的物模型进行操作，从而达到设备状态或行为变化。其中获取设备物模型使用XLinkTMLProbeAttributeTask

// 查询设备物模型
XLinkTMLProbeAttributeTask.newBuilder()
                    .setSendPolicy(XLinkSendDataPolicy.CLOUD_ONLY)
                    .setXDevice(xDevice)
                    .setListener(xxx)
                    .build();

获取设备物模型之前需要配置物模型的监听，即setTMLAttributeListener。因为获取到的数据将会通过上报的形式给到App。请查看 FAQ 相关问题解答

3.6、设置设备物模型属性

对设备的控制实际上就是对设备的物模型进行操作，从而达到设备状态或行为变化。其中设置设备物模型使用XLinkTMLSetAttributeTask

//快速转换成json数据的物模型参数
String content = new TMLAttributeRequestBuilder()
                    .addInput("scene_id", sceneId)
                    .toJsonString();

// 设置设备的物模型
XLinkTMLSetAttributeTask.newBuilder()
                    .setSendPolicy(XLinkSendDataPolicy.CLOUD_ONLY)
                    .setXDevice(xDevice)
                    .setTmlDataPayload(content)
                    .setListener(xxx)
                    .build();

3.7、调用设备物模型服务

相比于属性，服务可通过一条指令实现更复杂的业务逻辑。其中调用设备物模型服务使用XLinkTMLInvokeServiceTask

// 调用设备的物模型服务
XLinkTMLInvokeServiceTask.newBuilder()
                    .setSendPolicy(XLinkSendDataPolicy.LOCAL_ONLY)
                    .setXDevice(xDevice)
                    .setTmlServiceName(ProtocolConstant.TML_SERVICE_EXECUTE_SCENE)
                    .setTmlDataPayload(content)
                    .setListener(xxx)
                    .build();

五、云端消息推送

开发者可以通过 XLinkCloudListener 接收服务器的推送消息。这里的推送不单指通常意义上的文本消息的推送，还包含用户或者设备变化的消息推送。

1、推送消息对象

EventNotify类结构如下所示：

public class EventNoify{
    //消息来源类型
    public byte fromType;
    //消息来源ID
    public int fromId;
    //消息flag
    public byte notifyFlags;
    //消息类型
    public short messageType;
    //消息内容
    public byte[] payload;
}

• 消息来源类型

来源类型	说明	对应ID说明
FROM_TYPE_FROM_SERVER	来自服务端	0(固定值)
FROM_TYPE_FROM_DEVICE	来自设备	deviceId
FROM_TYPE_FROM_APP	来自APP	appId

• 消息类型

消息类型	值	说明
MSG_TYPE_DATA_POINT_CHANGED	1	设备通知，数据端点变化通知
MSG_TYPE_DATA_POINT_ALERT	2	设备告警，数据端点变化引起的告警
MSG_TYPE_DEVICE_SHARE	3	设备分享，设备管理员发出的分享
MSG_TYPE_PUSH_MSG	4	消息广播推送
MSG_TYPE_DEVICE_PROP_CHANGE	5	设备属性变化通知
MSG_TYPE_SUBSCRIPTION_CHANGE	6	设备与用户订阅关系变化通知
MSG_TYPE_ONLINE_STATE_CHANGE	7	设备在线状态变化通知
MSG_TYPE_ONLINE_STATE_ALERT	8	设备在线状态告警
MSG_TYPE_HOME_MESSAGE_NOTIFY	9	家庭消息通知，留言板消息
MSG_TYPE_HOME_INVITE	10	家庭邀请通知
MSG_TYPE_HOME_DEVICE_PERMISSION_CHANGED	11	家庭设备权限变化
MSG_TYPE_HOME_MEMBER_CHANGED	12	家庭成员变化
MSG_TYPE_HOME_DEVICE_CHANGED	13	家庭设备变化

2、推送消息对象的数据结构

各类型对应的数据请参考实体类结构：

消息类型	实体类
消息类型	实体类
1 设备通知，数据端点变化通知	DataPointChangedNotify
2 设备告警，数据端点变化引起的告警	DataPointAlertNotify
3 设备分享，设备管理员发出的分享	DeviceShareNotify
4 消息广播推送	PushMsgNotify
5 设备属性变化通知	DevicePropChangeNotify
6 设备与用户订阅关系变化通知	SubscriptionChangeNotify
7 设备在线状态变化通知	OnlineStateChangeNotify
8 设备在线状态告警	OnlineStateAlertNotify
9 家庭消息通知，留言板消息	HomeMessageNotify
10 家庭邀请通知	HomeMemberInvitedNotify
11 家庭设备权限变化	HomeDevicePermissionChangedNotify
12 家庭成员变化	HomeMemberChangedNotify
13 家庭设备变化	HomeDeviceChangedNotify

3、推送消息解析

开发者可以通过 EventNotify.messageType 的来判断消息类型，再根据 EventNotify.payload 来处理消息数据。XAPP SDK 内置了 EventNotifyHelper 类方便开发者解析消息推送，当需要对 EventNotify 的数据进行处理时，可以通过 EventNotifyHelper 进行快速辅助处理

//如以下示例，通过EventNotifyHelper可快速得到订阅信息变更的推送消息对象
SubscriptionChangeNotify = EventNotifyHelper.parseSubscriptionChangeNotify(eventNotify.payload);
 
若 EventNotifyHelper 中不存在对应的 API 可以直接进行通知事件的解析时，则可以使用以下的通用解析方法进行处理
 
 
//使用通用解析方式解析出home设备变更的推送消息对象
HomeDeviceChangedNotify notify = EventNotifyHelper.parseNotifyFromJson(
    eventNotify.data,
    HomeDeviceChangedNotify.class
    );

关于home相关的通知信息暂时都未提供相关的解析方法

强烈建议使用此辅助类进行事件的解析。由于通知事件实际上是字符串数据，当必须自行进行数据解析时，请忽略 payload 的前两个字节（表示该字符串的长度），再将 payload 的二进制数据按 UTF-8 的编码转成字符串再进行 json 解析。

注1：开发者在使用 XAPP SDK 时，如果想避免通过轮询的方式来更新状态，应利用上述通知来更新状态

注2：消息通知功能需用户登录，并使用云平台服务

六、设备订阅关系管理

通过 XLinkAddDeviceTask 可在云端建立用户和设备之间的订阅关系。订阅关系建立后，可使用 XLinkSyncDeviceListTask 获取与当前用户有订阅关系的设备列表。通过XLinkRemoveDeviceTask可解除订阅关系。

订阅关系	操作途径
订阅关系的建立	1.添加设备 2.设备分享 3.其他建立云端订阅关系的途径（如通过二维码订阅）
订阅关系的解除	1.删除设备 2.设备重新激活（设备重置后再连上云端，设备会重新激活） 3.其他解除云端订阅关系的途径

1、二维码订阅设备

除了使用通过正常的流程（扫描设备->添加订阅设备）订阅设备外，设备也允许使用二维码进行订阅。使用二维码订阅时不需要依赖于 XAPP SDK 的任务，直接通过 RESTFUL 接口即可进行处理。

• 二维码订阅时设备不要求一定在线，但是设备必须已经激活
• 二维码订阅操作必须设备支持允许
• 二维码订阅时必须用户已登录并携带有效 token

1.1、 配置设备支持二维码订阅

​ 您需要先登录物联云平台。

1. 产品必须添加一个二维码订阅专用的系统数据端点（$1002）
2. 该产品下的设备必须本身上报该数据端点值为 true，说明设备支持二维码订阅
3. 通过产品下选择某个设备，在设备详情界面查看其二维码

1.2、 二维码订阅设备

通过第三方方式获取到二维码图片中的文本信息之后，将文本信息提供给 RESTFUL 接口即可订阅设备。

• 直接使用接口订阅

URL: /v2/user/{user_id}/qrcode_subscribe
REQUEST:
{
    "qrcode": "二维码数据"
}
RESPONSE:
{
    "id": "设备ID",
    "mac": "设备MAC地址",
    "pid":"产品ID",
    "name":"设备名字"
    "sn":"序列号",
    "custom_property":{
        "{key}": "{value}"
    }
}

• 调用 XAPP SDK 封装 RESTFUL 接口进行订阅

String qrCode = "xxx";
Call<DeviceApi.QRCodeSubscribeResponse>  call = XLinkRestful.getApplicationApi().qrCodeSubscribeDevice(userId,request);

2、订阅关系变更回调

在订阅关系建立或解除时，以下两个回调会被触发：

• 设备信息变更

public void onDeviceChanged(XDevice xDevice, XDevice.Event event) {
   switch(event) {
       case SUBSCRIBE: // 与xDevice的订阅关系建立
           break;
       case UNSUBSCRIBE: // 与xDevice的订阅关系解除
           break;
   }
}

• 云端事件推送

public void onEventNotify(EventNotify eventNotify) {
    switch (eventNotify.messageType) {
        ...
        case EventNotify.MSG_TYPE_SUBSCRIPTION_CHANGE: {
            //消息类型为设备订阅关系发生变化
            EventNotifyHelper.SubscriptionChangeNotify notify = EventNotifyHelper.parseSubscriptionChangeNotify(eventNotify.payload);
             
            //根据设备ID获取变更的设备对象
            XDevice device = XLinkDeviceManager.getInstance().getDeviceFromDeviceId(eventNotify.device_id);
             
            //请注意不一定设备维护列表中一定会有此设备
            if(device!=null){
                if (notify.sub == EventNotifyHelper.SubscriptionChangeNotify.SUBSCRIBED) {
                        // 与xDevice的订阅关系建立
                }else if (notify.sub == EventNotifyHelper.SubscriptionChangeNotify.UNSUBSCRIBED) {
                        // 与xDevice的订阅关系解除
                }  
            }
        }
        ...
    }
    ...
}

尽管这两个回调都可用，强烈建议统一在 onEventNotify() 中进行所有云端消息推送的处理，可以避免一些不必要的错误操作；这是因为onDeviceChanged()方法只会在当前设备管理列表中存在相应的设备时，才能提供对应的设备对象进行回调，若设备管理列表中不存在相应的设备对象时，则无法回调该方法。

实际上onDeviceChanged()的回调也是来源于onEventNotify()，当设备的订阅关系变更时，XAPP SDK 将接收到云端的消息推送，在此过程中会再回调到onDeviceChanged()事件中。

当接收到订阅关系变化的通知时，XAPP SDK内部已断开和设备的连接，开发者应主动或提示用户刷新设备列表。

以上两个回调依赖云端连接，属于云端的推送消息。主要提供给APP开发者处理订阅关系被动建立或被动解除的情况（例如人为重置设备）。

如果是用户主动添加或删除设备（XLinkAddDeviceTask 或 XLinkRemoveDeviceTask ），那么在执行成功的时候就要进行后续处理，例如刷新设备列表、更新ui等等，不应该等待云端通知再进行处理

3、新增订阅方式——自v6.2版本起

此版本更新了一种新的订阅方式，该订阅方式与原订阅方式在实现处理上是完全不同的，相对于原有的订阅方式更加高效，灵活性也更强。

新的订阅方式主要通过以下流程进行：

1. 设备开启订阅使能
2. 扫描设备
3. 从设备获取 pinCode，校验码
4. 从云端获取订阅码
5. 发送订阅码给设备
6. 设备提交订阅码到云端验证
7. 接收云端订阅结果返回

这里的普通场景是指：设备与 APP 处于相同的网络中（相同的局域网），且设备与 APP 都能正常连接到外网（即可连接到云端）的情况。

在普通场景下，首先需要扫描到设备，之后仅需要使用一个任务即可完全以上所有操作，并且任务兼容旧的任务，是属于相同的任务类。

• 扫描设备 扫描设备与此前的任务是一致的，都是使用相同的任务进行扫描。

//扫描设备并监听设备扫描结果回调
XLinkScanDeviceTask task = XLinkScanDeviceTask.newBuilder()
        .setProductIds("pid1", "pid2")
        .setRetryInterval(3000)
        .setTotalTimeout(30000)
        .setScanDeviceListener(listener)
        .build();
XLinkSDK.startTask(task);

• 订阅设备 在扫描到设备之后，则可以将该设备对象作为参数，执行订阅设备任务。

//扫描设备并监听设备扫描结果回调
XLinkScanDeviceTask task = XLinkScanDeviceTask.newBuilder()
        .setProductIds("pid1", "pid2")
        .setRetryInterval(3000)
        .setTotalTimeout(30000)
        .setScanDeviceListener(listener)
        .build();
XLinkSDK.startTask(task);

注：

1. 以上任务与原订阅任务完全相同，差异在于需要提供来自设备的 pinCode
2. 若不设置设备的 pinCode，默认为物联云平台密钥，注意设备的 pinCode 应该是厂商决定的，只有厂商决定不使用 pinCode 时，才可以不设置

七、设备分享管理

设备的分享管理包括以下几部分：

• 将设备分享给其它用户
• 分享消息推送
• 处理分享消息

分享设备相关的所有操作并不完全都依赖于任务完成，有一些需要通过 http 接口获取数据，如设备的分享记录或列表；

相关分享接口请查看OPEN-API-设备功能

1、分享设备

通过 XLinkShareDeviceTask 可以将设备权限分享给其他在平台里已经注册的用户。

// 新建XLinkShareDeviceTask
XLinkShareDeviceTask task = XLinkShareDeviceTask.newBuilder()
        // 要分享出去的设备
        .setXDevice(device.getXDevice())
        // 分享模式
        .setMode(XLinkRestfulEnum.ShareMode.ACCOUNT)
        // 被分享者的账号
        .setAccount(account)
        // 该次分享有效期，单位秒，默认为 7200
        .setExpired(expired)
        // 设备的操作权限，默认允许读写
        .setAuthority(XLinkRestfulEnum.DeviceAuthority.RW)
        .setListener(new XLinkTaskListener<DeviceApi.ShareDeviceResponse>() {
            @Override
            public void onError(@NotNull XLinkCoreException exception) {
            }
 
            @Override
            public void onStart() {
            }
 
            @Override
            public void onComplete(DeviceApi.ShareDeviceResponse response) {
                //从结果中获取邀请码
                String invitedCode = response.inviteCode;
            }
        )
        .build();
XLinkSDK.startTask(task);

• 分享的模式类型

类型	说明
XLinkRestfulEnum.ShareMode.ACCOUNT	通过用户ID分享
XLinkRestfulEnum.ShareMode.QR_CODE	二维码方式分享
XLinkRestfulEnum.ShareMode.EMAIL	邮件方式分享

• 设备操作权限

类型	说明
XLinkRestfulEnum.DeviceAuthority.R	只读
XLinkRestfulEnum.DeviceAuthority.W	只写
XLinkRestfulEnum.DeviceAuthority.RW	可读写

2、分享消息推送

当接受分享方在线时，对方的 XLinkCloudListener 中的 onEventNotify 会收到类型为 EventNotify.MSG_TYPE_DEVICE_SHARE 的通知:

public void onEventNotify(EventNotify eventNotify) {
    //当SDK连接上云端，并接收到云端推送时，会回调这个方法
    switch (eventNotify.messageType) {
        case EventNotify.MSG_TYPE_DEVICE_SHARE:
            //收到分享请求
            handleDeviceShareNotify(eventNotify);
            break;
        ....
    }
}

注意：分享仅会有 EventNotify 的通知，设备订阅状态变更 onDeviceChanged() 的回调。 由于分享的设备还不存在当前用户的维护列表中，是无法回调通知设备状态发送了变化的

开发者可通过 EventNotifyHelper 来获取分享的类型，如下所示：

private void handleDeviceShareNotify(EventNotify eventNotify) {
    //解析出设备分析事件
    final EventNotifyHelper.DeviceShareNotify notify = EventNotifyHelper.parseDeviceShareNotify(eventNotify.payload);
    Log.d(TAG, "handleDeviceShareNotify: " + notify);
    ...
    switch (notify.type) {
        //收到新的分享
        case EventNotifyHelper.DeviceShareNotify.TYPE_RECV_SHARE:
            ...
            break;
        // 发出去的分享被接受
        case EventNotifyHelper.DeviceShareNotify.TYPE_ACCEPT_SHARE:
            ...
            break;
        // 原有的分享被取消
        case EventNotifyHelper.DeviceShareNotify.TYPE_CANCEL_SHARE:
            ...
            break;
        // 发出去的分享被拒绝
        case EventNotifyHelper.DeviceShareNotify.TYPE_DENY_SHARE:
            ...
            break;
    }
}

3、处理分享消息

开发者可以使用 XLinkHandleShareDeviceTask 对分享进行处理，如下所示：

XLinkHandleShareDeviceTask task = XLinkHandleShareDeviceTask.newBuilder()
    // 接受该次分享
    .setAction(action)
    // 待处理的分享的id
    .setInviteCode(notify.invite_code)
     // 当前用户的uid
    .setUid(XLinkUserManager.getInstance().getUid())
    .setListener(xxx)
    .build();
XLinkSDK.startTask(task);

其中 Action 为分享处理的行为：

行为	操作对象	说明
XLinkHandleShareDeviceTask.Action.ACCEPT	被分享者	接受该次分享
XLinkHandleShareDeviceTask.Action.ACCEPT_QRCODE	被分享者	接受该次二维码分享
XLinkHandleShareDeviceTask.Action.DENY	被分享者	拒绝这次分享
XLinkHandleShareDeviceTask.Action.CANCEL	发起分享者	取消已经分享出去的分享记录
XLinkHandleShareDeviceTask.Action.DELETE	被分享者或发起分享者	删除该次分享记录

详情可参考 demo 中关于设备分享部分的代码及注释

4、分享记录状态说明

当分享一个设备或接收到一个分享请求时，该用户都会产生一条分享记录。分享记录的状态如下：

值	类型	说明
accept	string	已接收
cancel	string	已取消
deny	string	已拒绝
invalid	string	无效的请求
overtime	string	超时
pending	string	等待接收
unsubscribed	string	设备已取消订阅，前一个状态必须是Accept

状态的部分变更参考说明如下：

1. 用户1分享设备给用户2，用户2未处理时，状态为pending；用户1删除设备后，分享记录状态不变；用户2再进行分享记录处理时，提示分享记录无效，状态为invalid
2. 用户1分享设备给用户2，用户2接受，状态为accpet；用户1删除设备后，分享记录状态变更为cancel
3. 用户1分享设备给用户2，用户2接受，状态为accpet；用户2删除设备后，分享记录状态变更为unsubscribed

八、内网固件升级-自v6.2.6.x版本起

在内网固件升级中，大致流程如下：

1. APP 向设备发送升级指令
2. 设备向 APP 查询升级任务信息
3. APP 向设备返回升级任务信息
4. 设备向 APP 下载升级固件文件
5. 设备升级后向 APP 发送升级结果

注：

1. 其中 APP 向设备发送的指令或信息都是通过任务执行的，所有相关任务可在 [API-Task API](../A-API/A-Task API.md) 中查询
2. 设备向 APP 发送的请求或信息都是以设备事件通知到 APP
3. 设备进行内网升级时，必须是设备内网连接已经成功连接上，可通过xDevice.getLocalConnectionState()==XDevice.State.CONNECTED进行检测

1、APP->设备：发送升级指令

APP 向设备发送升级指令通过XLinkLocalSendTriggerUpgradeTask任务执行

XLinkLocalSendTriggerUpgradeTask task = XLinkLocalSendTriggerUpgradeTask.newBuilder()
        //设置固件升级类型，请参考任务API详细说明
        .setFirmwareType(firmwareType)
        //设置操作的设备对象
        .setCoreDevice(xDevice)
        .setListener(new TaskListenerAdapter<Boolean>() {
            @Override
            public void onComplete(Task<Boolean> task, Boolean result) {
            }
 
            @Override
            public void onError(Task<Boolean> task, Throwable error) {
            }
        })
        .build();
XLinkSDK.startTask(task);

注意事项：该任务返回结果表示指令发送成功，暂不支持确认设备接收到该消息；如发送后设备无响应，应该考虑重试。

2、设备->APP：请求升级任务信息

在设备接收到 APP 发送的升级指令时，设备会向 APP 请求升级任务信息，将通过设备事件的方式将信息发送到 APP。因此使用内网固件升级功能时，必须监听设备事件回调事件进行处理。

configBuilder.setEventListener(new XLinkDeviceEventListener() {
            @Override
            public void onDeviceEventNotify(@NotNull XDevice device, @NotNull List<XLinkDeviceEvent> event, int from) {
                XLinkDeviceEvent devEvent = event.get(0);
                switch (devEvent.type) {
                    case XLinkDeviceEvent.TYPE_FIRMWARE_CHECK_UPGRADE_TASK:
                        //检测升级任务信息
                        FirmwareUpgradeTaskRequest taskRequest = devEvent.parseFrame2DeviceEvent(FirmwareUpgradeTaskRequest.class);
                        break;
                    case XLinkDeviceEvent.TYPE_FIRMWARE_REPORT_UPGRADE_RESULT:
                        //上报升级结果
                        FirmwareReportUpgradeResult result = devEvent.parseFrame2DeviceEvent(FirmwareReportUpgradeResult.class);
                        if (result.isSuccess()) {
                            //获取升级结果信息进行处理
                        }
                        break;
                    case XLinkDeviceEvent.TYPE_FIRMWARE_REPORT_VERSION:
                        //上报固件版本号
                        FirmwareReportVersion version = devEvent.parseFrame2DeviceEvent(FirmwareReportVersion.class);
                        break;
                }
            }
        });

3、APP->设备：返回升级任务信息

APP 首先需要确保从外部获取到有效的固件升级文件，以及该固件相关的版本信息等，这一部分是需要由外部提供的信息。当接收到来自设备的升级任务信息请求的事件时，通过解析出事件可以得到升级任务请求中携带的设备信息。

//解析检测升级任务请求``FirmwareUpgradeTaskRequest taskRequest = devEvent.parseFrame2DeviceEvent(FirmwareUpgradeTaskRequest.``class``);

升级任务请求中包括的信息如下：

字段名	类型	说明
firmwareType	byte	设备当前固件请求查询的固件类型
currentVersion	short	设备当前固件版本号
identifyCode	int	设备当前固件的标识码

根据任务请求中的参数，APP 需要向设备发送升级信息任务。设备升级需要从 APP 下载固件文件，所以 APP 需要提供下载服务器让设备下载固件文件。建议在返回升级任务前启动下载服务器做好下载准备，设备在成功接收到升级任务信息后将会立即进行固件文件下载操作。

XLinkLocalSendUpgradeTaskResultTask task = XLinkLocalSendUpgradeTaskResultTask.newBuilder()
        //通讯的设备对象
        .setCoreDevice(xDevice)
        //任务请求结果码
        .setCode(CoreConstant.FIRMWARE_RESULT_CODE_CHECK_VERSION_SUCCESS)
        //任务ID
        .setTaskId(taskId)
        //固件标识码，该标识码应该与设备请求的标识码一致，如果不一致则设备不会处理此任务
        .setIdentifyCode(identify)
        //固件类型，固件类型应该由提供的固件文件本身决定
        .setFirmwareType(firmwareType)
        //当前的固件版本号，该参数应该来自于设备的当前固件版本号，如果与设备当前固件版本不一致设备不会处理此任务
        .setCurrentVeresion(currentVersion)
        //固件类型的目标版本，即本次提供的固件文件的版本号
        .setTargetVersion((short) firmwareVersion)
        //固件文件的md5值
        .setFileMd5(StringUtil.getBytes(fileMd5))
        //固件文件长度
        .setFileSize(file.length())
        //固件文件下载地址，必须是内网设备可访问到的，并且是完整的下载地址
        .setDownloadUrl(downloadUrl)
        .setListener(new TaskListenerAdapter<Boolean>() {
            @Override
            public void onComplete(Task<Boolean> task, Boolean result) {
            }
 
            @Override
            public void onError(Task<Boolean> task, Throwable error) {
            }
        })
        .build();
XLinkSDK.startTask(task);

发送固件升级任务信息给设备时，需要注意一些参数的设置。

1. APP 有义务检测并保证固件的有效性，由于内网升级时固件是由 APP 提供的，因此提供的固件的版本号及文件信息等都必须是 APP 提供的。
2. 返回的任务信息中，固件标识码identifyCode与固件当前版本号currentVersion一般是来自于设备事件中的检测任务请求对象FirmwareUpgradeTaskRequest
3. 返回的任务信息中，固件类型firmwareType必须是当前提供的固件类型，而不是根据设备请求的固件类型提供。比如，当提供的固件为 MCU 升级固件时，设备请求的固件类型是 WIFI 类型时，不能提供设备请求信息中的固件类型，这里是真实提供的固件文件的固件类型。一般情况下设备请求的固件类型是取决于发送升级指令时提供的固件类型。
4. 固件文件下载地址必须是设备可访问到的完整的下载地址，如http://127.0.0.1:8080/firmware/file/123456.bin

4、设备->APP：设备返回升级结果

下载流程略。

设备在下载到固件后，校验固件文件正确之后会进行升级，升级后会将升级结果通过设备事件返回给 APP。设备返回升级结果时，并不保证该升级结果必定能接收到。

九、设备连接状态的刷新

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

注：

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

4.2、设备同步

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

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

注：

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

4.3、全局配置

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

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

十、设备物模型详解

物模型从属性、服务和事件三个维度，分别描述了其在物理空间中指代的实体是什么，能够做什么，能够对外提供哪些信息。从这三个维度定义好产品相应的物模型之后，也代表定义好了该产品的功能定义。在完成产品功能定义后，系统将自动生成该产品的物模型。

当设备的物模型发生变化，若设备已经连接到云端，那物模型的变化将会通过物联云平台提供的硬件 XAPP SDK，同步到云端上，以便厂商在云平台查看与收集设备的运行状态的变化。

1、物模型的智能转换

XAPP SDK 中提供了一个创建服务及属性的对象TMLAttributeRequestBuilder，只需要在addInput方法传入id和value，通过toJsonString可以转换物模型协议中所需要的json数据

String content = new TMLAttributeRequestBuilder()
                    .addInput("scene_id", sceneId)
                    .toJsonString();
            Task task = XLinkTMLInvokeServiceTask.newBuilder()
                    .setSendPolicy(XLinkSendDataPolicy.LOCAL_ONLY)
                    .setXDevice(device)
                    .setTmlServiceName(ProtocolConstant.TML_SERVICE_EXECUTE_SCENE)
                    .setTmlDataPayload(content)
                    .setListener(new TaskListenerAdapter<XLinkTMLServiceInvoke>() {
                        @Override
                        public void onError(Task<XLinkTMLServiceInvoke> task, Throwable error) {
                            super.onError(task, error);
                            System.err.println("服务调用失败了" + error.toString());
                        }

                        @Override
                        public void onComplete(Task<XLinkTMLServiceInvoke> task, XLinkTMLServiceInvoke result) {
                            super.onComplete(task, result);
                            System.err.println("服务调用成功了" + result);
                        }
                    })
                    .build();
            XLinkSDK.startTask(task);

十一、用户授权管理

1、授权信息说明

调用 XLinkUserAuthorizeTask 或 XLinkThirdPartyAuthorizeTask 后，XAPP SDK 内部会维护一个 XLinkUser 对象，里面包含了通讯所需的授权信息：

public class XLinkUser{
    //授权信息
    private String mAccessToken;
    //用于刷新当前授权信息的token
    private String mRefreshToken;
    //CM登录授权信息
    private String mAuthString;
    //用户ID
    private int mUid;
}

此对象可通过如下方法取出：

//通过用户管理对象
XLinkUser user = XLinkUserManager.getInstance().getUser();
//通过SDK直接获取
XLinkUser user = XLinkSDK.getUser();

注意事项： 1.请不要修改 XLinkUser 对象内的授权信，APP 运行时，XAPP SDK 会自动更新 XLinkUser 内部的授权信息。

2.开发者应避免自己缓存 XLinkUser 里的属性（例如把 accessToken 存在一个变量里）,应在每次需要的时候直接调用 XLinkUserManager.getInstance().getUser() 取出授权信息。

用户管理对象中提供了快捷获取相关授权信息的方法

//获取授权信息
XLinkUserManager.getInstance().getAccessToken();
//获取刷新token
XLinkUserManager.getInstance().getRefreshToken();
//获取用户ID
XLinkUserManager.getInstance().getUid();
//获取CM授权信息
XLinkUserManager.getInstance().getAuthString();

2、快捷登录授权

APP 首次打开时（未有用户信息），应跳转至登录页面让用户登陆。登陆动作应包含运行 XLinkUserAuthorizeTask 或 XLinkThirdPartyAuthorizeTask 。

如果要实现用户在下次打开 APP 时跳过登陆动作，那么在首次授权成功时需要保存授权信息，以便下一次快捷登录授权。

2.1、新快捷登录授权（自v6.2版本起）

自v6.2版本起，提供了一种新的快捷登录方式，该方式的目的与原快捷登录功能是一致的，但是解决了原功能可能潜在的问题。原快捷登录方式将用户信息提供给 XAPP SDK 后，XAPP SDK会自动在后台连接到云端服务器，但是存在可能是用户信息是无效或者过期，此时连接肯定失败，XAPP SDK 会通过回调通知用户信息无效。

在实际的应用场景中，可能会造成用户进入主界面后由于用户信息失效导致了需要返回登录界面进行重新登录；针对此情况可使用新的快捷登录授权方式进行处理。新的快捷登录方式将以任务的形式提供，允许设置在超时时间内尝试快捷登录，如果快捷登录失败了则会回调相应的错误信息；

XLinkConfig config = new XLinkConfig.Builder()
        ...
        .build();
XLinkAndroidSDK.init(config);
XLinkSDK.start();
 
//必须启动 SDK 之后才能执行任务
XLinkRefreshTokenTask task = XLinkRefreshTokenTask.newBuilder()
        .setRefreshToken(storgeRefreshToken)
        .setAuthString(storgeAuthString)
        .setUserId(storgeUid)
        .setListener(listener)
        .build();
XLinkSDK.startTask(task);

注意事项： 1.如果刷新凭证无效时，可能会在任务中止时停止 XAPP SDK 的运行，请注意在后续任务执行时需要重新启动 XAPP SDK，XAPP SDK 允许重复启动

2.当使用此新快捷登录方式，请不要在初始化 XAPP SDK 时设置 XLinkUser 信息，一旦在初始化时设置了用户信息，则会以原快捷登录授权方式进行处理，二者可能会造成冲突

3.此任务执行时会自动使用用户信息进行云端登录操作

2.2、原快捷登录授权（不推荐使用）

通过在初始化 XAPP SDK 时提供用户授权信息，XAPP SDK 将自动使用该用户授权信息连接到云端服务器而不需要进行登录。

//新建XLinkUser对象，设置保存了的授权信息
//AccessToken、RefreshToken、Uid、AuthString四个信息缺一不可
XLinkUser lastUser = new XLinkUser();
lastUser.setAccessToken(storgeAccessToken);
lastUser.setRefreshToken(storgeRefreshToken);
lastUser.setUid(storgeUid);
lastUser.setAuthString(storgeAuthString);
 
XLinkConfig config = new XLinkConfig.Builder()
                ...
                // 设置授权信息
                .setXLinkUser(lastUser)
                ...
                .build();

设置好以后，在XLinkSDK.start()的同时，XAPP SDK会自动验证授权信息是否合法，合法则进行后续一系列的云端操作和内部操作。

3、重新授权

一般来说，需要重新授权有如下几个原因：

• 用户被踢出（单点登录）
• token过期（含缺失，格式错误等原因）
• 用户主动退出

当出现如上情况时，XLinkUserListener 相关方法会回调：

public void onUserLogout(LogoutReason reason) {
    switch (reason) {
        case SINGLE_SIGN_KICK_OFF:
            //用户被踢出
            break;
        case TOKEN_EXPIRED:
            //过期
            break;
        case USER_LOGOUT:
            //用户主动退出
            break;
    }
}

退出登录原因	操作建议
SINGLE_SIGN_KICK_OFF TOKEN_EXPIRED	主动调用XLinkSDK.logoutAndStop()停止XAPP SDK并需要重新登录
USER_LOGOUT	勿需特殊操作（因为 USER_LOGOUT 由XLinkSDK.logoutAndStop()触发）

注意事项：XLinkSDK.logoutAndStop() 操作会触发USER_LOGOUT事件,处理时请注意避免由于在USER_LOGOUT事件中重复调用该方法引起造成循环逻辑

4、用户凭证维护

在 XAPP SDK 中，默认情况下都会维护授权信息（凭证包含在授权信息中）。登录后获取到的授权信息如下：

{
  //调用凭证
  "access_token": "110ABC119EDF120",
  //刷新凭证
  "refresh_token": "110ABC119EDF120",
  //用户ID
  "user_id": "110120119",
  //有效期（单位：秒）
  "expire_in": "7200",
  //认证码
  "authorize": "110abc119edf120"
}

存在两种不同作用的凭证：调用凭证（简称凭证）与刷新凭证

1. 登录后获取到的用户信息中包括了调用凭证和刷新凭证，其中调用凭证用于所有需要授权信息的接口，但是时效比较短（约2小时）；刷新凭证时间较长(以天为单位，约14天)。所有的请求中需要使用的是有效的调用凭证，刷新凭证不用于授权作用
2. 当调用凭证过期后，在刷新凭证的有效期内可以通过刷新凭证更新并继续使用

在 XAPP SDK 中，当调用凭证无效时，会尝试使用刷新作证去刷新，当无法正常刷新时，才会提示凭证（token）是过期的。所以一般情况下，只要 XAPP SDK 使用是正常的，那么通过以下方式获取到的凭证都是正常可以用的。

XLinkUserManager.getInstance().getAccessToken();

注意事项：强烈建议即取即用，即使是短时间的使用也不要保存起来使用，因为无法确认是否下一秒中调用凭证就可能被刷新掉了。

如果是使用到 restful 接口中一些已有的接口，可以直接通过以下方式调用已有的接口，该请求中是会直接使用 XAPP SDK 中维护的凭证而不需要额外的任何处理。

XLinkRestful.getInstance().getApplicationApi().xxx

注意事项：必须 XAPP SDK 已经初始化过才能正常使用 XLinkRestful

API

API 模块是将所有开发者需要使用的类及其相关的 API 接口陈列出来，以便开发者在使用时可以方法查询相关方法的使用方式及其作用。

主要涉及的有以下几个：

• API-XLinkSDK - XAPP SDK 的入口与操作
• API-Task API - 所有的 Task 的方法及使用
• API-XLinkDeviceManager - 设备管理类，与设备相关操作
• API-DeviceHelper - 设备辅助类，提供辅助方法方便设备操作
• API-XLinkConstant - 常量类
• API-XDevice - 设备对象类，设备属性及相关方法
• API-XLinkTMLManager - 设备物模型管理类，管理设备物模型
• API-XLinkUser - 用户信息类
• API-XLinkUserManager - 用户信息管理类，管理用户信息
• API-XLinkConfig.Builder - XAPP SDK 配置信息
• API-EventNotify - 推送消息类，来自云端推送的消息
• API-EventNotifyHelper - 推送消息辅助类，提供辅助方法方便解析推送消息

分类	相关类
任务类	Task API
配置类	XLinkConfig.Builder
物模型相关	XLinkTMLManager
设备相关	XDevice、XLinkDeviceManager、DeviceHelper
用户相关	XLinkUser、XLinkUserManager
云端消息相关	EventNotify、EventNotifyHelper
常量类	XLinkConstant

DeviceHelper

设备辅助类，提供了大量方法用于辅助有关数据的处理，绝大部分的方法是 SDK 内部会使用到，不禁止开发者调用，但是不推荐使用。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

一、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
暂无	-	-

二、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

默认情况下，不推荐未列出的其它方法，即使是开放的方法，因为部分方法可能仅 SDK 内部使用。

2.1、generateDeviceTag

@NotNull
public static String generateDeviceTag(String mac, String pid)

• 方法说明：

静态方法，通过 mac 与 pid 生成标准的设备标识，该标识可用于任何需要使用设备标识的地方

• 参数说明：

参数名	类型	说明
mac	String	设备 mac
pid	String	设备产品ID

• 返回值：String，设备标识；当参数有效非空时，将根据规则成功有效的设备标识，否则返回空字符串

2.2、separateMacAndPidFromDeviceTag

@NotNull
public static String[] separateMacAndPidFromDeviceTag(String devTag)

• 方法说明：

静态方法，从设备标识中获取 mac 与 pid 参数，请注意这里并不保证返回的数据一定是正确的，仅按规则进行拆解获取到 mac 与 pid，若设备标识来自 SDK 或由设备自身生成，则能拆解出正确的 mac 与 pid

• 参数说明：

参数名	类型	说明
devTag	String	设备标识

• 返回值：String[]，mac 与 pid；拆解成功时返回2个元素的字符串数组，第1个字符串为 mac，第二个字符串为 pid，拆解不成功时返回2个元素均为空字符串

2.3、getPairingSessionId

public static short getPairingSessionId(String deviceMac)

• 方法说明：

静态方法，获取设备的 pairingId，该值在 ==0 时无效

• 参数说明：

参数名	类型	说明
deviceMac	String	设备 mac 地址

- 返回值：short，配对ID；SDK 与设备建立连接的凭证，返回0时无效

2.4、getPairingSessionKey

@NotNull
public static byte[] getPairingSessionKey(String deviceMac)

• 方法说明：

静态方法，获取设备的 pairingKey

• 参数说明：

参数名	类型	说明
deviceMac	String	设备 mac 地址

• 返回值：byte[]，配对密钥；SDK 与设备建立连接的凭证加密使用的密钥，返回值不为 null，不存在配对密钥时返回空字节数组

错误码说明与使用

一、前提说明

此错误码仅对v6版本 XAPP SDK 适用

二、新旧错误码对照表

由于旧的错误码为具体的某个流程，而且一般情况下就是失败的错误码并没有更多的信息，所以旧的错误码实际可能是对应新的多个错误码，以下是原错误码与新错误码之间的一些对照关系。

新错误码与旧错误码的差异主要如下：

• 旧错误码为枚举类型数据
• 新错误码均为整型数据，且每一个错误码明确代表了一种错误情况

当在升级 XAPP SDK 版本使用时出现无法处理的错误码可以在以下对照表中查找对应的解决方案

旧错误码中存在一些错误码是多种可能错误的复合体，而新错误码将具体返回当前操作中任何导致操作失败的错误码（可能来自设备，也可能是数据错误，或者内部错误），所以存在一个旧错误码可能对应某个操作中多个新的错误码，这是正常的。

注意：所有新错误码都是XLinkErrorCodes类下的整型常量，以下省略该类的引用

旧错误码	新错误码	对应模块/说明备注
所有ERROR_API_开头的错误码	对应的ERROR_API_xxx新错误码	ERROR_API_开头的为API相关的错误码,名称与意义不变
ERROR_UNKNOWN_CORE_ERROR_CODE	ERROR_UNKNOWN	未知错误
ERROR_API_UNKNOWN_ERROR	ERROR_API_UNKNOWN	未知API错误
ERROR_RUNTIME_EXCEPTION	ERROR_OTHER_EXCEPTION	其它来源错误
ERROR_UNSUPPORTED_PROTOCOL_VERSION	PROTOCOL_VERSION_NOT_SUPPORTED	协议版本不支持
ERROR_TASK_TIMEOUT	TASK_TIMEOUT	任务超时
ERROR_TASK_CANCELED	TASK_CANCELED	任务取消
ERROR_TASK_DEPENDENCE_TIMEOUT	TASK_DEPENDENCE_TIMEOUT	任务依赖超时,暂不抛出该错误
ERROR_USER_NOT_AUTHORIZED	-	该错误为API返回的没有权限错误,新错误码不再将权限问题转换返回,直接返回对应API错误码
ERROR_DEVICE_NOT_CONNECTED_CLOUD	DEVICE_FAIL_CLOUD_NOT_CONNECTED	设备未进行云端连接,可能在设备操作时返回(如设置数据端点)
ERROR_DEVICE_NOT_CONNECTED_LOCAL	DEVICE_FAIL_LOCAL_NOT_CONNECTED	设备未进行本地连接,可能在设备操作时返回(如设置数据端点)
ERROR_LOCAL_PAIRING_LIMIT_REACHED	PAIRING_LOCAL_FAIL_REACH_PAIRING_LIMIT	本地配对次数达到上限(参考以上解决方案)
ERROR_AUTH_CODE_NOT_PROVIDED ERROR_LOCAL_SCAN_DEVICE_EMPTY_PID ERROR_LOCAL_OPEN_SESSION_INVALID_PARAM ERROR_LOCAL_PAIRING_INVALID_PARAM ERROR_LOCAL_DEVICE_NOT_SET	PARAMS_NOT_EXIST	参数未提供
ERROR_INVALID_PARAMS	PARAMS_INVALID	无效参数
ERROR_CLOUD_SET_DATA_POINT_FAIL	-	对应设置云端数据端点中所有可能出现的错误(参考以下操作或APP-SDK错误码)
ERROR_LOCAL_SET_DATA_POINT_FAIL	-	对应设置本地数据端点中所有可能出现的错误(参考以下操作或 API)
ERROR_CLOUD_GET_DATA_POINT_FAIL	-	对应获取云端数据端点中所有可能出现的错误(参考以下操作或 API)
ERROR_LOCAL_GET_DATA_POINT_FAIL	-	对应获取本地数据端点中所有可能出现的错误(参考以下操作或 API)
ERROR_CLOUD_SUBSCRIBE_DEVICE_FAIL	-	对应在订阅设备操作中所有可能出现的错误(参考以下操作或 API)
ERROR_LOCAL_PAIRING_FAIL ERROR_LOCAL_PAIRING_HANDSHAKE_FAIL	-	对应添加/订阅设备流程中所有可能出现的错误(参考以下操作或 API)
ERROR_CLOUD_GET_TICKET_FAIL ERROR_CLOUD_CONNECT_CLOUD_FAIL	-	不再支持该错误,可能对应TASK_TIMEOUT或其它通用性错误
ERROR_NONE ERROR_CLOUD_DISCONNECT_CLOUD_FAIL ERROR_CLOUD_DEVICE_OPEN_SESSION_FAIL ERROR_CLOUD_DEVICE_CLOSE_SESSION_FAIL ERROR_LOCAL_CLOSE_SESSION_FAIL ERROR_LOCAL_OPEN_SESSION_FAIL ERROR_LOCAL_UNPAIRING_FAIL ERROR_LOCAL_DEVICE_NOT_BOUND ERROR_LOCAL_GET_DEVICE_INFO_FAIL	-	不再抛出该错误(或者该错误不被开发者感知)
ERROR_LOCAL_SESSION_ENCRYPT_FAIL ERROR_LOCAL_SESSION_DECRYPT_FAIL	PROTOCOL_FAIL_ENCRYPT_SESSION PROTOCOL_FAIL_DECRYPT_SESSION	通讯异常错误，正常情况下不会抛出，但在设备操作时可能会抛出异常
ERROR_MQTT_CLIENT_DISCONNECTED ERROR_MQTT_CLIENT_INNER_ERROR ERROR_MQTT_CLIENT_INVALID_PARAMS ERROR_MQTT_CLIENT_NOT_CONNECTED_BROKER	MQTT_FAIL_CLIENT_DISCONNECTED MQTT_FAIL_CLIENT_INNER_ERROR MQTT_FAIL_CLIENT_PARAMS_NOT_EXIST	内部错误,不应该抛出

新旧错误码的对照关系仅仅是用于提供从旧错误码快速对应到新的相关错误的参考途径，请重点根据下述错误码分类进行错误码处理。

三、基础错误码

基础错误码的来源可能是

• 内部参数或者是逻辑错误
• 未知错误

基础的错误码一旦发生了，除了少数错误码需要开发者进行校验检测（如参数不正确等），其它的并没有即时可用的解决方案，因为本身可能是由于内部错误或者某些逻辑检测返回的错误（如无法识别的未知错误或者BUG）

3.1、基础错误码表

错误码	字段定义	意义
300101	TASK_TIMEOUT	任务超时
300102	TASK_CANCELED	任务取消
300103	TASK_DEPENDENCE_TIMEOUT	任务依赖等待超时(如云端任务需要云端连接成功才能操作,等待期间云端未能连接成功导致超时)
400101	ERROR_UNKNOWN	未知错误
400102	ERROR_API_UNKNOWN	未知的API错误,或者解析API错误码时出错
400103	ERROR_OTHER_EXCEPTION	其它的异常信息,查看原始异常信息获取错误信息
400104	ERROR_SOCKET_TIMEOUT	socket 连接超时
400105	ERROR_OPERATION_NOT_SUPPORTED	当前操作不支持无法执行
400201	MQTT_FAIL_CLIENT_PARAMS_NOT_EXIST	client操作时参数不合法
400202	MQTT_FAIL_CLIENT_NOT_EXIST	client不存在,无法进行相关通讯操作
400203	MQTT_FAIL_CLIENT_DISCONNECTED	mqtt client未连接成功
400204	MQTT_FAIL_CLIENT_INNER_ERROR	client内部出错,属于client的未知错误
400205	MQTT_FAIL_LOCAL_CLIENT_INIT	初始化本地client失败
400206	MQTT_FAIL_CLOUD_CLIENT_INIT	初始化云端client失败
400207	MQTT_FAIL_LOCAL_PUBLISH	本地发布topic失败
400208	MQTT_FAIL_CLOUD_PUBLISH	云端发布topic失败
400301	PROTOCOL_VERSION_NOT_SUPPORTED	协议版本不支持
400313	PROTOCOL_FAIL_CLOUD_CM_CONNECTED	云端连接失败
400314	PROTOCOL_FAIL_CLOUD_CM_DISCONNECTED	断开云端连接失败
400315	PROTOCOL_FAIL_PACKET_DATA	打包数据包出错
400316	PROTOCOL_FAIL_PARSE_DATA	解析数据包出错
400401	DEVICE_FAIL_LOCAL_NOT_CONNECTED	设备本地未连接
400402	DEVICE_FAIL_CLOUD_NOT_CONNECTED	设备云端未连接
400405	DEVICE_FAIL_DEVICE_NOT_EXIST	维护的设备不存在
400601	PARAMS_INVALID	参数不合法(参数存在但是未获取需要的信息,如设备对象对象存在但获取不到Mac)
400602	PARAMS_NOT_EXIST	需要的参数不存在(参数不存在,Null或者Nil)

基础错误码是理论上在任何任务中都可能出现的，大部分情况下基础错误码中最常见的错误码就是“未知错误”、“参数不存在或不合法”以及一些网络相关的错误（如 socket 超时）。

其它的错误码默认情况下即使有产生也是内部的错误码，XAPP SDK 将会在内部进行处理，除非无法通过正常流程处理，则会将错误信息抛出。

3.2、处理建议

对于基础错误码中，部分错误码需要开发人员介入校验，建议处理如下：

错误码	字段定义	意义	处理建议
400301	PROTOCOL_VERSION_NOT_SUPPORTED	协议版本不支持	XAPP SDK 版本与设备版本是否一致或者兼容，V6 XAPP SDK 兼容V5设备，但V5设备仅能使用V5的 XAPP SDK
400602	PARAMS_NOT_EXIST	需要的参数不存在(参数不存在,Null或者Nil)	参数缺少，请检查一下是否是传入的参数是否完整，大部分情况下可能是忽略了设备对象参数
400601	PARAMS_INVALID	参数不合法	传入的参数是不正确的参数导致了无法正常处理

四、根据操作分类

根据设备操作可以对每个不同操作环节可能出现的错误码进行分类，其中主要的操作包括了：

• 扫描设备
• 添加订阅设备
• 操作设备(设置数据端点)
• 移除设备(取消订阅)

4.1、扫描设备错误码

扫描操作会一直执行直到任务超时或者被中止为止，必然会抛出TASK_TIMEOUT错误，暂无其它错误码，不需要处理。当扫描到设备时就是扫描到设备，当未扫描成功时即未扫描到设备。

4.2、添加订阅设备错误码

添加订阅过程需要进行与设备进行通讯，并交换信息及校验工作，之后需要与云端再发起设备校验工作，最终将设备与用户关联起来。所以这个过程涉及的多个过程，出现的错误码也相关较多一点。绝大部分的错误码都是会在内部进行校验并处理，大部分情况下订阅失败可能是由于订阅流程出错或者是任务超时。

4.2.1、错误码表

错误码	字段定义	意义
100401	PAIRING_HANDSHAKE_LOCAL_FAIL_DH_PARAMS_INVALID	本地配对握手DH参数不合法
100402	PAIRING_HANDSHAKE_LOCAL_FAIL_PUBLIC_KEY_INVALID	本地配对握手Public Key不合法
100403	PAIRING_HANDSHAKE_LOCAL_FAIL_TICKET_VERIFY	本地Ticket验证失败(为空、不匹配)
100404	PAIRING_HANDSHAKE_LOCAL_FAIL_PIN_VERIFY	本地PinCode验证失败(为空、不匹配)
100405	PAIRING_HANDSHAKE_LOCAL_FAIL_DEVICE_NOT_READY	设备不在配对状态
100600	PAIRING_LOCAL_SUCCESS	本地配对成功
100601	PAIRING_LOCAL_FAIL_REACH_PAIRING_LIMIT	本地配对达到上限
100900	SESSION_HANDSHAKE_LOCAL_SUCCESS	本地会话握手成功
100901	SESSION_HANDSHAKE_LOCAL_FAIL_UNKNOWN_PAIRING_ID	本地会话未知pairing id
100902	SESSION_HANDSHAKE_LOCAL_FAIL_VERIFY	本地会话验证失败
100903	SESSION_HANDSHAKE_LOCAL_FAIL_DH_PARAMS_INVALID	本地会话DH参数不合法
100904	SESSION_HANDSHAKE_LOCAL_FAIL_PUBLIC_KEY_INVALID	本地public key不合法
101701	GET_TICKET_LOCAL_FAIL_UNKNOWN_TYPE	未知ticket type
201602	SUBSCRIBE_DEVICE_FAIL_DEVICE_INFO_INVAILD	云端订阅设备失败，设备信息有误
201603	SUBSCRIBE_DEVICE_FAIL_TICKET_INVAILD	云端订阅设备失败，Ticket校验失败
201604	SUBSCRIBE_DEVICE_FAIL	云端订阅设备失败
201605	SUBSCRIBE_DEVICE_FAIL_DEVICE_MODE_LIMITED	云端订阅设备失败，设备订阅模式限制订阅失败。
400304	PROTOCOL_FAIL_ENCRYPT_PAIRING	配对解密失败
400305	PROTOCOL_FAIL_DECRYPT_PAIRING	配对加密失败
400306	PROTOCOL_FAIL_DECRYPT_PAIRING_HANDSHAKE	配对握手加密失败
400307	PROTOCOL_FAIL_ENCRYPT_PAIRING_HANDSHAKE	配对握手加密失败
400308	PROTOCOL_FAIL_ENCRYPT_PIN_CODE	pinCode加密失败
400309	PROTOCOL_FAIL_DECRYPT_PIN_CODE	pinCode解密失败
400310	PROTOCOL_FAIL_PAIRING_HANDSHAKE_NOT_EXIT	配对握手会话信息不存在
400311	PROTOCOL_FAIL_PAIRING_NOT_EXIST	配对信息不存在

4.2.2、处理建议

对于部分可处理或者分析的错误码,建议处理如下

错误码	字段定义	意义	处理建议
100405	PAIRING_HANDSHAKE_LOCAL_FAIL_DEVICE_NOT_READY	设备不在配对状态	设备可能存在某个硬件按钮或者配置，需要通过某种操作开启配对模式，当设备处于配对模式中时才允许进行设备的配对操作。 正常情况下设备在进入配对模式后会持续一段时间(具体机制请以硬件说明为准)
100601	PAIRING_LOCAL_FAIL_REACH_PAIRING_LIMIT	本地配对达到上限	设备配对次数已达上限，部分设备默认情况下只允许配对16次(具体限制请以硬件说明为准)
201602	SUBSCRIBE_DEVICE_FAIL_DEVICE_INFO_INVAILD	云端订阅设备失败，设备信息有误	请检查设备是否异常，或当前设备是否有添加到管理台产品中，或者当前企业下是否有该设备
201605	SUBSCRIBE_DEVICE_FAIL_DEVICE_MODE_LIMITED	云端订阅设备失败，设备订阅模式限制订阅失败	一般情况下是由于设备的订阅限制引起的，请在后台管理系统中->产品信息->订阅模式，是否仅允许单人订阅

4.3、操作设备

设备操作是包括了获取设备数据端点和设置设备数据端点的操作。

4.3.1、错误码表

错误码	字段定义	意义
错误码	字段定义	意义
101301	SET_DATAPOINT_LOCAL_FAIL	设置数据端点失败
101302	SET_DATAPOINT_LOCAL_FAIL_UNAUTHORISED	未授予设置权限
101303	SET_DATAPOINT_LOCAL_FAIL_DEVICE_FAULT	设备问题
101304	SET_DATAPOINT_LOCAL_FAIL_TYPE_ERROR	数据端点类型错误
101501	GET_DATAPOINT_LOCAL_FAIL_FLAG_NOT_SUPPORTED	flag参数不支持
101502	GET_DATAPOINT_LOCAL_FAIL_UNAUTHORISED	未授予获取权限
110301	PROBE_LOCAL_FAIL_FLAG_NOT_SUPPORTED	flag参数不支持
110302	PROBE_LOCAL_FAIL_UNAUTHORISED	未授予获取权限
200801	SET_DATAPOINT_CLOUD_FAIL	云端设置数据端点失败
200802	SET_DATAPOINT_CLOUD_FAIL_UNAUTHORISED	未授予设置权限
201001	GET_DATAPOINT_CLOUD_FAIL	云端获取数据端点失败,服务不可用
400401	DEVICE_FAIL_LOCAL_NOT_CONNECTED	设备本地未连接
400402	DEVICE_FAIL_CLOUD_NOT_CONNECTED	设备云端未连接
400405	DEVICE_FAIL_DEVICE_NOT_EXIST	维护的设备不存在
400406	DEVICE_FAIL_DEVICE_ID_IS_ZERO	设备ID不能为0
400312	PROTOCOL_FAIL_SESSION_NOT_EXIST	本地会话信息不存在

4.3.2、处理建议

对于大部分的操作错误，一般情况下都可以考虑重试（任务超时的情况下TASK_TIMEOUT），如果有明确的错误码返回，可以根据错误码信息进行处理，大部分的错误码都与配置相关

错误码	字段定义	意义	处理建议
101302	SET_DATAPOINT_LOCAL_FAIL_UNAUTHORISED	数据端点未授予设置权限	请在后台管理系统确认产品是否允许设置数据端点
101303	SET_DATAPOINT_LOCAL_FAIL_DEVICE_FAULT	设备问题	请检查设备
101502	GET_DATAPOINT_LOCAL_FAIL_UNAUTHORISED	数据端点未授予获取权限	请在后台管理系统确认产品是否允许获取数据端点
101304	SET_DATAPOINT_LOCAL_FAIL_TYPE_ERROR	数据端点类型错误	请检查设置的数据端点类型是否正确(如确认无误请参考 XAPP SDK 相关的指南确认是否使用方式有误)
110302	PROBE_LOCAL_FAIL_UNAUTHORISED	PROBE设备未授予获取权限	请在后台管理系统确认产品是否允许PROBE设备
200802	SET_DATAPOINT_CLOUD_FAIL_UNAUTHORISED	数据端点未授予设置权限	请在后台管理系统确认产品是否允许设置数据端点
400406	DEVICE_FAIL_DEVICE_ID_IS_ZERO	设备ID不能为0	请检查设备ID是否为0

4.4、移除设备

移除设备的话主要包括取消设备之前的关联,同时并取消用户与设备的绑定关系,该操作与HTTP请求有关,所以可能会返回关于HTTP的错误,请参考HTTP的错误码说明进行处理.

BaseLog.Config

配置日志输出信息的构建类，该类用于创建日志输出的配置信息

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

一、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
Loggable	接口	日志输出接口

二、Field

以下为此类中的常用字段及说明。

2.1、Attributes

由于此类包含的属性较多，不一一罗列其属性的getter/setter方法，以下字段都支持对应的方法，方法列表中不再赘述。大部分情况下，以下属性为仅读属性

字段名	字段类型	getter支持返回null	说明
字段名	字段类型	getter支持返回null	说明
defaultTag	String	-	默认的日志输出标识
logPreFix	String	-	日志的前缀文本
logoutPath	String	-	日志输出文件路径
enabledLogFile	boolean	-	是否启用日志输出文件
debugLevel	int	-	日志输出等级，默认为 ERROR
bufferLevel	int	-	日志输出到文件的等级，默认为 ERROR
loggable	Loggable	-	日志输出接口

debugLevel 与 bufferLevel 等级均使用 Loggable 中的等级常量。

2.2、Loggable Level

字段名	值	说明
VERBOSE	2	冗余的日志等级，所有的日志内容都会输出
DEBUG	3	调试的日志等级，大部分的日志会集中以此等级输出
INFO	4	信息的日志等级，小部分非调试型日志以此等级输出
WARN	5	警告的日志等级，部分警告型日志以此等级输出
ERROR	6	错误的日志等级，异常或错误日志以此等级输出
NONE	Integer.MIN_VALUE	无日志等级，不输出日志

三、Relevant Class

以下为此类中的关联类或内部类

3.1、Loggable

Loggable 为日志输出接口，在实际的不同平台或者环境下，可能输出的日志输出的目标是不一样的（如控制台，文件或其它程序等），通过此接口可以定义将日志信息输出到什么位置显示。

int log(int level, @Nullable String tag, @NotNull String msg, @Nullable Throwable e)

EventNotify

事件通知类，来自云端的事件通知，具体的通知内容实际是由通知的数据决定的。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

一、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
EventNotifyHelper	辅助类	事件通知辅助处理类，详情请参考 API-EventNotifyHelper

二、Field

以下为此类中的常用字段及说明。

2.1、Attributes

由于设备对象包含的属性较多，不一一罗列其属性的getter/setter方法，以下字段都支持对应的方法，方法列表中不再赘述。大部分情况下，以下属性为仅读属性

字段名	字段类型	getter支持返回null	说明
fromType	byte	-	通用事件通知，一般不需要使用
fromId	int	-	消息来源ID，根据来源类型确认该字段所属对象，可能是服务端、设备或 APP。来自服务端时 ID 为0
notifyFlags	byte	-	消息标识
messageType	short	-	消息类型标识
payload	byte[]	否	数据内容

2.2、NotifyFlags

数据类型标识

位	说明
0	来自 Server 事件
1	来自 Device 事件
2	来自 APP 事件
3	收到事件以后要不要应用，默认不需要应答

2.3、MessageType

消息类型

字段名	字段类型	值	说明
MSG_TYPE_DATA_POINT_CHANGED	int	0x01	设备通知，数据端点变化通知
MSG_TYPE_DATA_POINT_ALERT	int	0x02	设备告警，数据端点变化引起的告警
MSG_TYPE_DEVICE_SHARE	int	0x03	设备分享，设备管理员发出的分享
MSG_TYPE_PUSH_MSG	int	0x04	消息广播推送
MSG_TYPE_DEVICE_PROP_CHANGE	int	0x05	设备属性变化通知
MSG_TYPE_SUBSCRIPTION_CHANGE	int	0x06	设备与用户订阅关系变化通知
MSG_TYPE_ONLINE_STATE_CHANGE	int	0x07	设备在线状态变化通知
MSG_TYPE_ONLINE_STATE_ALERT	int	0x08	设备在线状态告警
MSG_TYPE_HOME_MESSAGE_NOTIFY	int	0x09	家庭消息通知，留言板消息
MSG_TYPE_HOME_INVITE	int	0x0a	家庭邀请通知
MSG_TYPE_HOME_DEVICE_PERMISSION_CHANGED	int	0x0b	家庭设备权限变化
MSG_TYPE_HOME_MEMBER_CHANGED	int	0x0c	家庭成员变化
MSG_TYPE_HOME_DEVICE_CHANGED	int	0x0d	家庭设备变化

三、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

3.1、isFromServer

public boolean isFromServer()

• 方法说明：

判断当前消息是否来自服务端，来自服务端则 fromId 的值为0

• 返回值：来自服务端返回 true，否则返回 false

3.2、isFromDevice

public boolean isFromDevice()

• 方法说明：

判断当前消息是否来自设备

• 返回值：来自设备返回 true，否则返回 false

3.3、isFromApp

public boolean isFromApp()

• 方法说明：

判断当前消息是否来自 APP

• 返回值：来自 APP 返回 true，否则返回 false

3.4、isNeedResponse

public boolean isNeedResponse()

• 方法说明：

是否需要应答事件通知，一般情况下都不需要，可以不关注此方法

• 返回值：若需要应答返回 true，否则返回 false

EventNotifyHelper

云端消息推送处理辅助类，用于快捷解析并获取到推送消息内容。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

一、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
DataPoints	实体类	事件通知的数据端点信息，与 XLinkDataPoint 是不同的，见下文
DataPointChangedNotify	实体类	数据端点变化通知，见下文
DataPointAlertNotify	实体类	数据端点变化引起的告警，见下文
DeviceShareNotify	实体类	设备管理员发出的分享，见下文
PushMsgNotify	实体类	消息广播推送，见下文
DevicePropChangeNotify	实体类	设备属性变化通知，见下文
SubscriptionChangeNotify	实体类	设备与用户订阅关系变化通知，见下文
OnlineStateChangeNotify	实体类	设备在线状态变化通知，见下文
OnlineStateAlertNotify	实体类	设备在线状态告警，见下文
HomeMessageNotify	实体类	家庭消息通知，见下文
HomeMemberInvitedNotify	实体类	家庭邀请通知，见下文
HomeDevicePermissionChangedNotify	实体类	家庭设备权限变化，见下文
HomeMemberChangedNotify	实体类	家庭成员变化，见下文
HomeDeviceChangedNotify	实体类	家庭设备变化，见下文

二、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

2.1、parseNotifyEntityFromJson

public static <T> T parseNotifyEntityFromJson(byte[] payload, Class<T> clazz)

• 方法说明：

将云端推送的消息解析成相关的实体数据类，数据类型通过参数指定需要返回的参数类型。所有此类中的消息实体类型都可以通过此方法进行解析

• 参数说明；

参数名	参数类型	说明
payload	byte[]	来自云端推送消息返回的消息对象 EventNotify 中的字段数据
clazz	Class	解析的目标数据实体类型
T	T	泛型参数

• 返回值：T，解析后的实体类型对象；参数无效或解析失败时允许返回为 null

三、Relevant Class

以下为此类中的关联类或内部类

3.1、EventNotifyHelper.DataPoints

事件通知中使用的数据端点信息，注意与 API-XLinkDataPoint 是有区别的，二者是不同的

字段名	字段类型	说明
index	int	数据端点索引
value	Object	数据端点值

3.2、EventNotifyHelper.DataPointChangedNotify

数据端点变化通知

字段名	字段类型	说明	是否必须
index	int	数据端点索引；如果是多条件告警，数据端点列表会在 dps 中	否
value	boolean	数据端点值；如果是多条件告警，数据端点列表会在 dps 中	否
dps	List	多条件告警数据端点及值列表	否
msg	String	通知、告警消息实体，内容具体在管理台设置	否

3.3、EventNotifyHelper.DataPointAlertNotify

数据端点变化引起的告警

字段名	字段类型	说明	是否必须
index	int	数据端点索引；如果是多条件告警，数据端点列表会在 dps 中	否
value	boolean	数据端点值；如果是多条件告警，数据端点列表会在 dps 中	否
dps	List	多条件告警数据端点及值列表	否
msg	String	通知、告警消息实体，内容具体在管理台设置	否

3.4、EventNotifyHelper.DeviceShareNotify

设备管理员发出的分享

字段名	字段类型	说明
device_id	int	设备 ID
invite_code	String	设备分享邀请码
type	int	分享操作类型

• Type

字段名	字段值	说明
TYPE_RECV_SHARE	0	分享请求
TYPE_ACCEPT_SHARE	1	接受分享
TYPE_DENY_SHARE	2	拒绝分享
TYPE_CANCEL_SHARE	3	取消分享

3.5、EventNotifyHelper.PushMsgNotify

厂商推送的消息广播

字段名	字段类型	说明	是否必须
msg_type	String	消息类型	是
action_type	String	命令类型	是
url	String	链接	否
command	String	命令	否
title	String	消息标题	是
content	String	消息内容	是

• ActionType

字段名	字段值	说明
ACTION_TYPE_URL	url	打开链接，返回此类型时参数为 url
ACTION_TYPE_COMMAND	command	用户自定义动作，返回此类型时参数为 command

3.6、EventNotifyHelper.DevicePropChangeNotify

设备属性变化通知

字段名	字段类型	说明	是否必须
device_id	int	设备 ID	是
type	String	变化类型	是
operator	String	操作员，若管理台修改值为0	是

• Type

字段名	字段值	说明
TYPE_INFO	info	设备基本属性
TYPE_PROP	prop	设备扩展属性
TYPE_ONLINE	online	设备上线
TYPE_OFFLINE	offline	设备下线

3.7、EventNotifyHelper.SubscriptionChangeNotify

用户和设备订阅关系发生变化通知

字段名	字段类型	说明	是否必须
device_id	int	设备 ID	是
sub	int	设备与当前用户的订阅关系	是

• Sub

字段名	字段值	说明
SUBSCRIBED	1	已订阅
UNSUBSCRIBED	0	已取消订阅

3.8、EventNotifyHelper.OnlineStateChangeNotify

设备在线状态变化引发的通知

字段名	字段值	说明	是否必须
device_id	int	设备 ID	是
state	int	设备在线状态	是
msg	String	管理台设置的通知内容	是

• State

字段名	字段值	说明
OFFLINE	0	离线
ONLINE	1	在线

3.9、EventNotifyHelper.OnlineStateAlertNotify

设备在线状态变化引发的告警

字段名	字段值	说明	是否必须
device_id	int	设备 ID	是
state	int	设备在线状态	是
msg	String	管理台设置的通知内容	是

• State

字段名	字段值	说明
OFFLINE	0	离线
ONLINE	1	在线

3.10、EventNotifyHelper.HomeMessageNotify

家庭消息通知

字段名	字段值	说明	是否必须
home_id	String	家庭 ID	是
from_id	int	消息发送者 ID	是
from_name	String	消息发送者名称	是
type	String	消息类型	是
title	String	消息标题	是
content	String	消息内容	是
home_name	String	家庭名称	是

• Type

字段名	字段值	说明
TYPE_NOTIFY	notify	通知
TYPE_SHARE	share	分享
TYPE_DELETE	delete	家庭被管理员删除

3.11、EventNotifyHelper.HomeMemberInvitedNotify

家庭成员邀请通知

字段名	字段值	说明	是否必须
home_id	String	家庭 ID	是
from_id	int	邀请者 ID	是
from_name	String	邀请者名称	是
to_id	int	被邀请者 ID	是
to_name	String	被邀请者名称	是
invite_id	String	邀请的请求 ID	是
opt	String	操作类型	是
home_name	String	家庭名称	是

• Opt

字段名	字段值	说明
OPERATION_INVITED	invite	发起邀请
OPERATION_ACCEPT	accept	接受
OPERATION_DENY	deny	拒绝

3.12、EventNotifyHelper.HomeDevicePermissionChangedNotify

家庭成员对某个设备的权限发生变化时通知

字段名	字段值	说明	是否必须
home_id	String	家庭 ID	是
device_id	int	设备 ID	是
user_id	int	成员 ID	是
authority	String	对设备的权限	是
home_name	String	家庭名称	是

• Authority

字段名	字段值	说明
AUTHORITY_WRITE	W	可写
AUTHORITY_READ	R	可读
AUTHORITY_READ_WRITE	RW	可读写

3.13、EventNotifyHelper.HomeMemberChangedNotify

家庭成员添加/移除时通知

字段名	字段值	说明	是否必须
字段名	字段值	说明	是否必须
home_id	String	家庭 ID	是
user_id	int	成员 ID	是
name	String	用户名称	是
role	String	家庭成员角色	是
type	String	添加或者删除	是
home_name	String	家庭名称	是

• Type

字段名	字段值	说明
TYPE_ADD	add	用户加入了该家庭，所有成员用户会收到这个通知
TYPE_REMOVE	remove	用户移除(被移除)了该家庭，所有成员都会收到这个通知

3.14、EventNotifyHelper.HomeDeviceChangedNotify

家庭设备添加/移除时通知

字段名	字段值	说明	是否必须
home_id	String	家庭 ID	是
device_id	int	设备 ID	是
type	String	操作类型	是
home_name	String	家庭名称	是

• Type

字段名	字段值	说明
TYPE_ADD	add	用户加入了该家庭，所有成员用户会收到这个通知
TYPE_REMOVE	remove	用户移除(被移除)了该家庭，所有成员都会收到这个通知

Task API

一、Introduction

1、Callback Usage

所有的任务在默认情况下，处理成功将回调onCompleted(result)方法，失败将回调onError(xlinkCoreException)方法

当返回错误时，通过错误信息可以获取错误码及异常信息，以提供调试帮助或者是用户提示上的说明。

public void onError(XLinkCoreException ex){
    //获取错误码
    int code = ex.getErrorCode();
    //获取错误信息对象,包括错误码与错误说明
    XLinkErrorDesc errorDesc = ex.getErrorDesc();
    //错误码名称(英文)
    String name = ex.mErrorName;
    //错误码说明(中文)
    String desc = ex.mErrorDesc;
     
    //快捷获取错误码名称或说明
    String name = ex.getErrorName();
    String desc = ex.getErrorDescStr();
 
    //当错误为未知错误时，可能存在原始错误码，可以查看是否存在某原始的错误码
    //这是由于某些错误码可能在当前版本不兼容或不存在，或者可能是云端返回的 API 错误码暂时未同步
    if(code == XLinkErrorCodes.ERROR_UNKNOWN){
        int srcErrorCode = ex.getSourceErrorCode();
    }
 
    //当异常信息为其它异常或者未知异常时，有可能存在原始异常信息，也可以获取到处理
    if (code == XLinkErrorCodes.ERROR_OTHER_EXCEPTION)
            Throwable srcSrc = ex.getSrcThrowable();
            if (srcSrc != null) {
                //原始的异常信息
            }
        }
    }   
}

注意事项： 1.当回调错误时，异常信息是必然存在的，不为空 2.每个异常必定存在一个错误码及错误信息，错误信息不为空

2、Erorr Codes

所有错误码主要分为两类：

• 一类是通用的错误码，即可能在任何任务中出现的错误码，该部分的错误码一般情况下是没有对应的解决方案，通常可以通过重试任务尝试解决（也存在一些错误码在出现时是必定无法正常使用，即使重试也是一样的结果）
• 另一类是对应不同的任务可能出现的错误码，如一些设备错误码不可能出现在与用户相关任务中。

注意事项： 1.所有包含 CLOUD 的错误码都是与云端通讯有关的 2.所有未说明解决方案的说明该错误无法进行处理，可尝试重试 3.绝大部分的错误码是不会抛出（SDK 内部会进行处理），这里仅是列出所有理论上任务中可能抛出的错误码，所有错误码请参考 APP-SDK错误码

通用部分的错误码，并附上大致说明与一些解决方案，特定错误码在后续具体任务中说明，不在此处一一列出：

错误码	说明	建议解决方案
TASK_TIMEOUT	任务超时	重试操作
TASK_CANCELED	任务取消	-
ERROR_UNKNOWN	未知错误	建议通过工单报告错误码或者更详细说明错误发生情况,如有源错误码可一并提供，可以尝试重试操作
ERROR_API_UNKNOWN	未知的API错误,或者解析API错误码时出错	建议通过工单报告错误码
ERROR_OTHER_EXCEPTION	其它的异常信息	通过查看原始异常信息确定解决方案
ERROR_SOCKET_TIMEOUT	socket 连接超时	检查网络后重试操作
ERROR_OPERATION_NOT_SUPPORTED	当前操作不支持无法执行	-
PROTOCOL_VERSION_NOT_SUPPORTED	协议版本不支持	-
DEVICE_FAIL_DEVICE_NOT_EXIST	设备对象不存在	-
DEVICE_FAIL_DEVICE_ID_IS_ZERO	设备ID不能为0	-
PARAMS_INVALID	参数不合法	确认参数有效再重试
PARAMS_NOT_EXIST	需要的参数不存在	确认参数有效再重试

3、ask Type

所有任务主要是与设备通讯的任务，但是有一部分任务是通过接口请求处理的，在该类任务中只会出现 API 错误码而不会出现其它的给定的错码误。所有 API 错误码请参考APP-SDK错误码

任务类型	说明
http任务	仅通过 HTTP 接口通讯的任务，只返回与 API 有关的错误码
普通任务	包含使用 MQTT 协议通讯的任务（可能存在 HTTP 通讯），同时可能返回 API 错误码或 SDK 错误码

在下述任务中，未进行特殊说明的情况下，设置参数时调用的方法都是添加前缀set

4、Task Default Timeout

在 SDK 中，主要的任务都是有固定默认的超时时间，该时间只是作为一个参考时间，开发者可根据实际的情况（如网络环境或使用场景）自行修改。

任务	默认时间（ms）	任务说明
XLinkScanDeviceTask	45000	扫描设备任务
XLinkAddDeviceTask	45000	添加设备任务
XLinkUserAuthorizeTask	30000	普通用户登录任务
XLinkThirdPartyAuthorizeTask	30000	第三方用户登录任务
XLinkSmsAuthroizeTask	30000	手机短信登录任务
XLinkRefreshTokenTask	30000	新快捷登录任务
XLinkRemoveDeviceTask	30000	移除设备任务
XLinkSyncDeviceListTask	30000	同步设备列表任务
XLinkSyncHomeDeviceListTask	30000	同步单个Home设备列表任务
XLinkTMLSetAttributeTask	10000	设置物模型属性任务
XLinkTMLInvokeServiceTask	10000	调用物模型服务任务
XLinkTMLProbeAttributeTask	10000	获取物模型任务
XLinkProbeDataPointTask	10000	探测数据端点任务
XLinkShareDeviceTask	30000	分享设备任务
XLinkHandleShareDeviceTask	30000	处理分享操作任务
XLinkConnectDeviceTask	30000	连接设备任务

5、Reference

以下为任务中的关联的Class及相关说明

类名	类型	说明
XLinkSendDataPolicy	枚举类	通讯策略
XLinkRestfulEnum.UserSource	枚举类	用户来源
XLinkRestfulEnum.ShareMode	枚举类	分享模式
XLinkRestfulEnum.DeviceAuthority	枚举类	设备控制权限
XLinkHandleShareDeviceTask.Action	枚举类	分享设备处理操作
XLinkConstant	常量类	所有常用的常量将存在于此类中，包括常用的flag和部分默认参数值，详情请查看 API-XLinkConstant

二、User Info Task

1、XLinkUserAuthorizeTask

本任务用于物联云平台的账号（ demo 中注册或者是已有的 APP 账号）登录授权

• 任务名称:XLinkUserAuthorizeTask
• 任务类型:HTTP任务
• 参数说明:

参数	类型	说明	是否必须
phone	String	手机号	使用手机账号登录时必须填写
phoneZone	String	手机区号	否，默认为+86（自v6.2版本起）
email	String	邮箱	使用邮箱账号登录时必须填写
password	String	密码	是
corpId	String	企业ID	是
timeout	int	超时时间	否，默认超时时间请查看本文档的第一章节的第4小点【Task Default Timeout】
listener	TaskListener	监听事件	是

• 返回数据:UserAuthApi.UserAuthResponse

{
    "userId":0,//用户ID
    "accessToken":"token",//授权信息
    "refreshToken":"refreshToken",//授权信息过期时用于刷新授权信息
    "expireIn":7200,//授权信息有效时间,单位秒
    "authorize":"xxx"//云端CM登录授权信息
}

注意事项：登录的账号为 APP 的账号，不是企业账号，可以通过调用接口或者 demo 进行注册获取

• 错误码:返回API错误码,请参考APP-SDK错误码

2、XLinkSmsAuthorizeTask——自v6.2版本起

本任务用于短信验证码登录账号

• 任务名称:XLinkSmsAuthorizeTask
• 任务类型:HTTP任务
• 参数说明:

参数	类型	说明	是否必须
corpId	String	企业ID	是
phone	String	手机号	用于登录的手机号
phoneZone	String	手机区号	否，默认为+86
verifyCode	String	短信验证码	是
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

• 返回数据:UserAuthApi.UserSmsAuthResponse

{
    "userId":0,//用户ID
    "accessToken":"token",//授权信息
    "refreshToken":"refreshToken",//授权信息过期时用于刷新授权信息
    "expireIn":7200,//授权信息有效时间,单位秒
    "authorize":"xxx"//云端CM登录授权信息
}

注意事项： 1.短信验证码需要提前通过接口获取到 2.若未注册过的手机号将会自动注册账号

• 错误码:返回API错误码,请参考APP-SDK错误码

3、XLinkThirdPartyAuthorizeTask

本任务用于第三方接入物联云平台的账号登录授权

• 任务名称:XLinkThirdPartyAuthorizeTask
• 任务类型:HTTP任务
• 参数说明:

参数	类型	说明	是否必须
openId	String	第三方账号换取的openId	是
accessToken	String	第三方账号换取的token	是
source	enum	第三方账号来源	是，类型请参考附录1
name	String	昵称	否
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

• 返回数据:ThirdPartyAuthApi.AuthResponse

{
    "userId":0,//用户ID
    "accessToken":"token",//授权信息
    "refreshToken":"refreshToken",//授权信息过期时用于刷新授权信息
    "expireIn":7200,//授权信息有效时间,单位秒
    "authorize":"xxx"//云端CM登录授权信息
}

• 错误码:返回 API 错误码,请参考APP-SDK错误码

4、XLinkRefreshTokenTask——自v6.2版本起

本任务用于刷新凭证授权，根据开发指南及上述登录任务说明，登录后将返回的用户信息主要有几个字段，其中包括了accessToken——用于用户请求授权凭证，以及refreshToken刷新授权凭证——用于刷新用户请求授权凭证。

通过刷新授权凭证即可获取到新的用户请求授权凭证，用于其它正常的请求处理了。本任务可用于快捷登录，详情请参考进阶篇-用户授权管理

• 任务名称:XLinkRefreshTokenTask
• 任务类型:HTTP任务
• 参数说明:

参数	类型	说明	是否必须
refreshToken	String	用户的刷新凭证	是
userId	int	用户ID,用于 CM 服务器登录	是
authString	int	CM 服务器授权信息,用于 CM 服务器登录	是
xlinkUser	XLinkUser	此参数为上述所有参数的集合体,与上述所有参数二择一即可	否
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

• 返回数据:UserApi.TokenRefreshResponse

{
    "access_token":"token",//授权信息
    "refresh_token":"refreshToken",//授权信息过期时用于刷新授权信息
    "expire_in":"7200"//授权信息有效时间,单位秒
}

• 调用方式：

刷新 token 时必须的参数是 refreshToken、userId、authString，该部分的参数都可以通过 XLinkUser 一次性提供。

//直接设置必须参数调用
Task task = XLinkRefreshTokenTask.newBuilder()
    .setRefreshToken(token)
    .setUserId(id)
    .setAuthString(auth)
    .setListener(listener)
    .build();
 
//创建用户对象一次性提供所有参数
XLinkUser user = new XLinkUser();
user.setRefreshToken(token);
user.setUid(id);
user.setAuthString(auth);
 
Tsak task =  XLinkRefreshTokenTask.newBuilder()
    .setXLinkUser(user)
    .setListener(listener)
    .build();

三、Device Control Task

1、XLinkScanDeviceTask

本任务用于扫描局域网中的设备，在设备扫描到后才可以进行设备的订阅操作

• 任务名称:XLinkScanDeviceTask
• 任务类型:普通任务
• 参数说明:

参数	类型	说明	是否必须
productIds	List	产品ID，用于过滤扫描到的设备	是
filterDevices	boolean	是否过滤设备，每个扫描到的设备仅会回调一次	否，默认值为 false
totalTimeout	int	总超时时间	否
scanDeviceListener	XLinkScanDeviceListener	扫描设备监听回调	是
listener	TaskListener	与scanDeviceListener相同，使用一个回调即可，重置设置时注意两者会互相覆盖	否

• 返回数据:使用 scanDeviceListener 时，回调在onScanResult(XDevice)，设备数据类型请参考API-XDevice
• 错误码

错误码	说明
TASK_TIMEOUT	任务超时

注意事项： 1.扫描设备时 APP 需要与设备在同一局域网中 2.扫描任务未取消任务的情况下，扫描任务总是会超时

2、XLinkAddDeviceTask

本任务用于在扫描到设备之后，添加并订阅设备

• 任务名称:XLinkAddDeviceTask
• 任务类型:普通任务
• 参数说明:

参数	类型	说明	是否必须
xDevice	XDevice	添加的设备对象	是
connectLocal	boolean	是否添加后进行本地连接，仅需要云端连接时，可以设置为false	否，默认为true
needSubscription	boolean	是否需要订阅设备，当需要绑定当前用户与设备关系时，设置为true	否，默认为true
totalTimeout	int	总超时时间	否
pinCode	byte[]	校验码	否
ticket	byte[]	校验码,兼容旧数据	否，推荐忽略
listener	TaskListener	监听事件	是

• 返回数据:XDevice，添加成功将返回设备对象，设备数据类型请参考API-XDevice
• 错误码:

错误码	说明
基本错误码	按上述基本错误码说明处理
SUBSCRIBE_DEVICE_FAIL_DEVICE_INFO_INVAILD	设备信息无效，请确认后台填写了有效的设备信息，是否未将设备添加到产品列表下
SUBSCRIBE_DEVICE_FAIL_TICKET_INVAILD	云端订阅设备失败，Ticket校验失败
SUBSCRIBE_DEVICE_FAIL	订阅失败，服务器内部错误，建议提供日志反馈工单
SUBSCRIBE_DEVICE_FAIL_DEVICE_MODE_LIMITED	设备订阅模式问题，请确认后台是否允许多人订阅
PAIRING_LOCAL_FAIL_REACH_PAIRING_LIMIT	配对次数达到16次，请重置设备后重新尝试
PAIRING_HANDSHAKE_LOCAL_FAIL_DEVICE_NOT_READY	设备不在配对状态

自v6.2版本起，提供了新的订阅方式，以下为新订阅方式中可能返回的错误码

新错误码	说明
SUBCODE_STATE_CLOUD_FAIL_SERVER_SUBSCRIBE_FAIL	云端执行订阅时发生错误
SUBCODE_STATE_CLOUD_FAIL_DEVICE_MODE_LIMITED	设备订阅模式问题，请确认后台是否允许多人订阅
SEND_SUBCODE_LOCAL_FAIL_REFUSE	设备拒绝被订阅，请确认是否开启订阅开关
SEND_SUBCODE_LOCAL_FAIL_REACH_PAIRING_LIMIT	设备配对次数达上限
SEND_SUBCODE_LOCAL_FAIL_DECRYPT	设备解密出错，订阅码无法正确解析

注意事项： 1.添加设备时根据不同的网络情况与设备硬件，可能需要的时间是不同的，根据情况为添加设备操作设置自主的超时时间 2.添加设备为 APP 与设备进行连接，并产生关联关系；订阅设备为将 APP 与设备的关联关系绑定并提交到云端存储，二者存在一定差异性，详情可参考 FAQ 3.自v6.2版本起，提供了新的订阅方式，详情请查看进阶篇-设备订阅关系管理

3、XLinkConnectDeviceTask——自v6.2版本起

本任务用于将设备添加到设备管理列表中进行维护或者是切换设备的连接策略，在v6版本 SDK 中，大部分情况下不需要使用此任务，此任务更多是用于辅助使用的功能。通常情况下设备的状态变更都建议通过监听设备的状态回调——XLinkDeviceStateListener进行处理。

此任务的特点是通过任务连接的设备，在给定超时时间内如果能成功按相应的连接策略连接成功，则返回结果；否则返回错误。但是不管结果是否成功，设备都会添加到设备管理列表中维护，即使设备是当给定时间内无法连接成功，后续也可能是连接成功的。

另一个可能需要使用到此任务的场景是需要改变设备的连接策略。在绝大部分情况下应该都不需要手动强制改变连接策略，当需要时，可通过此任务进行操作。同时，通过设备管理对象也可以直接进行切换设备的连接策略，只是处理和调用方式与此任务不同而已，详情请查看进阶篇-设备连接状态管理

• 任务名称:XLinkConnectDeviceTask
• 任务类型:普通任务
• 参数说明:

参数	类型	说明	是否必须
xDevice	XDevice	需要连接的设备对象	是
connectionFlags	int	连接策略	否
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

• 返回数据：XDevice，连接成功返回的设备对象，设备数据类型请参考API-XDevice
• 错误码：TASK_TIMEOUT，连接失败时为超时

注意事项： 1.当设备不在管理列表中时，会将设备添加到管理列表中处理；当设备在管理列表中时，使用该设备相关的信息 2.连接策略允许不设置，不设置时使用当前设备管理列表中的连接策略进行处理 3.设备不管是否连接成功都会存在设备管理列表中，即使任务返回失败后续也会持续维护设备状态，依然有可能连接成功

• 连接策略 连接策略在常量类XLinkConstant中定义

字段	意义	说明
FLAG_POLICY_NONE_CONNECTION	无连接策略	不进行任何处理，延用当前设备状态
FLAG_POLICY_AUTO_CONNECTION	进行云端、内网自动连接	当设备云端或内网断开时，尝试自动重新连接
FLAG_POLICY_LOCAL_AUTO_CONNECTION	内网自动连接	当设备内网状态断开时会尝试进行自动连接
FLAG_POLICY_LOCAL_ONCE_CONNECTION	内网一次性连接	当设备内网状态断开后不会再进行连接，切换为此连接策略时，不影响当前内网的连接状态
FLAG_POLICY_CLOUD_AUTO_CONNECTION	云端自动连接	当设备云端状态断开时会尝试进行自动连接
FLAG_POLICY_CLOUD_ONCE_CONNECTION	云端一次性连接	当设备云端状态断开后不会再进行连接，切换为此连接策略时，不影响当前云端的连接状态

XLinkConnectDeviceTask task = XLinkConnectDeviceTask.newBuilder()
        //设置连接设备
        .setXDevice(device)
        //设置连接策略，多个连接策略可通过或操作合并在一起
        .setConnectionFlags(XLinkConstant.FLAG_POLICY_LOCAL_ONCE_CONNECTION |
        XLinkConstant.FLAG_POLICY_CLOUD_AUTO_CONNECTION)
        .setListener(listener)
        .build();
XLinkSDK.startTask(task);

4、XLinkTMLSetAttributeTask

本任务用于控制设备，设置设备的物模型属性从而使设备状态或者行为发生变化

• 任务名称: XLinkTMLSetAttributeTask
• 任务类型:普通任务
• 参数说明:

参数	类型	说明	是否必须
xDevice	XDevice	操作的设备对象	是
totalTimeout	int	总超时时间，超时时任务结束	否
sendPolicy	XLinkSendDataPolicy	临时发送策略，可改变此次操作采用当前的发送策略，若未设置使用全局（初始化时）的发送策略	否，默认使用全局的发送策略
payload	String	json数据的物模型参数	是
listener	TaskListener	监听事件	是

• 返回数据:XDevice，设置成功将返回设备对象，设备数据类型请参考API-XDevice

注意事项：通常情况下，设置属性物模型属性需要设备状态在线（即能成功与设备进行通讯）

5、XLinkTMLInvokeServiceTask

本任务用于控制设备，设置设备的物模型服务从而使设备状态或者行为发生变化

• 任务名称: XLinkTMLInvokeServiceTask
• 任务类型:普通任务
• 参数说明:

参数	类型	说明	是否必须
xDevice	XDevice	操作的设备对象	是
totalTimeout	int	总超时时间，超时时任务结束	否
sendPolicy	XLinkSendDataPolicy	临时发送策略，可改变此次操作采用当前的发送策略，若未设置使用全局（初始化时）的发送策略	否，默认使用全局的发送策略
serviceName	String	物模型服务名称	是
payload	String	json数据的物模型参数	是
listener	TaskListener	监听事件	是

• 返回数据:XDevice，设置成功将返回设备对象，设备数据类型请参考API-XDevice

注意事项：通常情况下，设置属性物模型服务需要设备状态在线（即能成功与设备进行通讯）

6、XLinkTMLProbeAttributeTask

本任务用于获取设备物模型，通常设备状态或行为是从物模型表现出来的，根据物模型可以获取到设备不同的数据或者状态

• 任务名称: XLinkTMLProbeAttributeTask
• 任务类型:普通任务
• 参数说明:

参数	类型	说明	是否必须
xDevice	XDevice	操作的设备对象	是
totalTimeout	int	总超时时间，超时时任务结束	否
sendPolicy	XLinkSendDataPolicy	临时发送策略，可改变此次操作采用当前的发送策略，若未设置使用全局（初始化时）的发送策略	否，默认使用全局的发送策略
listener	TaskListener	监听事件	是

• 任务执行成功后，物模型结果将会在XLinkTMLDeviceAttributeListener回调，所以需要在初始化SDK的时候配置好setTMLAttributeListener

注意事项：通常情况下，获取数据端点需要设备状态在线（即能成功与设备进行通讯）

7、XLinkRemoveDeviceTask

本任务用于删除掉当前 SDK 维护的设备对象，并且取消当前用户与该设备的绑定关系

• 任务名称:XLinkRemoveDeviceTask
• 任务类型:HTTP任务
• 参数说明:

参数	类型	说明	是否必须
xDevice	XDevice	操作的设备对象	是
userId	int	用户ID	否，不推荐设置，默认使用当前登录用户的id
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

• 返回数据:String，移除成功返回空字符串，移除失败返回错误信息
• 错误码:

错误码	说明
基本错误码	按上述基本错误码说明处理
API错误码	-

注意事项：删除设备会取消掉当前用户与该设备的绑定关系，即云端不再保存二者的绑定关系，删除设备成功后再次同步设备列表时将不会出现已删除的设备

8、XLinkSyncDeviceListTask

本任务用于从云端后台同步，同步当前用户账户绑定的设备对象，同步下来的设备对象在设备正常可用时，则可以通过云端进行设备控制

• 任务名称:XLinkSyncDeviceListTask
• 任务类型:HTTP任务
• 参数说明:

参数	类型	说明	是否必须
connectLocal	boolean	同步设备列表后是否进行设备本地连接	否，默认 true
userId	int	用户ID	否，不推荐设置，默认使用当前用户 id
version	int	版本号	否，不推荐设置
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

• 返回数据:XDevice，设置成功将返回设备对象，设备数据类型请参考API-XDevice
• 错误码:返回 API 错误码或超时

注意事项： 1.同步的设备列表中的所有设备都是与当前用户存在绑定关系，无绑定关系的设备将不会同步到 2.默认情况下同步后的设备会自动进行云端与内网连接，

9、XLinkShareDeviceTask

本任务用于进行设备分享操作，并返回是否分享成功的结果

• 任务名称:XLinkShareDeviceTask
• 任务类型:HTTP任务
• 参数说明:

参数	类型	说明	是否必须
xDevice	XDevice	分享的设备对象	是
openId	String	第三方账号openId	是，分享第三方账号必须设置，普通账号不需要
openIdSource	XLinkRestfulEnum.UserSource	第三方账号来源	是，分享第三方账号必须设置，普通账号不需要
account	String	分享账号	是，与第三方账号互斥，普通账号分享必须设置
mode	XLinkRestfulEnum.ShareMode	分享类型	是，分享模式
authority	XLinkRestfulEnum.DeviceAuthority	设备操作权限	否，默认允许读写
expired	int	分享码有效期，单位秒	否，默认7200s
uid	int	分享的目标用户id	是
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

注意事项： 1.设备分享目标账号可以是普通账号，也可以是第三方账号，注意两者是分享是互斥的 2.openId、openIdSource 都是第三方账号分享使用的参数 3.account、uid 为普通账号分享使用的参数，根据分享模式选择不同的参数

10、XLinkHandleShareDeviceTask

本任务用于处理设备分享消息

• 任务名称:XLinkHandleShareDeviceTask
• 任务类型:HTTP任务
• 参数说明:

参数	类型	说明	是否必须
inviteCode	String	分享码	是
action	XLinkHandleShareDeviceTask.Action	分享操作行为	是
uid	int	当前用户ID	否，默认为当前用户id
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

• 返回数据:String，处理成功返回空字符串，处理失败返回错误
• 错误码:返回 API 错误码或超时

四、Other Task

1、XLinkLocalSendTriggerUpgradeTask-自6.2.6.x版本起

本任务用于内网固件升级时，向设备发送触发检测升级任务的指令。关于内网固件升级操作，请参考进阶篇-设备固件升级

• 任务名称：XLinkLocalSendTriggerUpgradeTask
• 任务类型：普通任务
• 参数说明：

参数	类型	说明	是否必须
firmwrareType	byte	固件类型	是
xDevice	XDevice	设备对象	是
timeout	int	超时时间	否
listener	TaskListener	监听事件	是

• 固件类型 固件类型在XLinkConstant常量类中定义

字段	意义
FIRMWARE_TYPE_WIFI	WIFI固件类型
FIRMWARE_TYPE_MCU	MCU固件类型

• 返回数据：返回数据为Boolean，表示是否发送指令成功
• 错误码：返回超时

注意事项：此任务只能确认是否成功发送指令，暂时无法确保指令是否送达；若出现发送成功后短时间内设备无任务操作或反应，则应该考虑重发。

2、XLinkLocalSendUpgradeTaskResultTask-自6.2.6.x版本起

本任务用于内网固件升级时，接收到设备的获取升级任务请求时，返回发送升级任务详细信息。关于内网固件升级操作，请参考进阶篇-设备固件升级

• 任务名称：XLinkLocalSendUpgradeTaskResultTask - 任务类型：普通任务
• 参数说明：

参数	类型	说明	是否必须
xDevice	XDevice	设备对象	是
code	byte	请求结果码	是
firmwareType	byte	固件版本类型	是
currentVersion	short	当前固件版本号	是
targetVersion	short	目前升级固件版本号	是
identifyCode	int	识别码	是
taskId	String	任务ID	是
fileMd5	byte[]	固件文件md5值	是
fileSize	long	固件文件字节长度	是
url	String	固件文件下载地址	是
timeout	超时时间	否
listener	TaskListener	监听事件	是

• 固件类型 固件类型在XLinkConstant常量类中定义

字段	意义
FIRMWARE_TYPE_WIFI	WIFI固件类型
FIRMWARE_TYPE_MCU	MCU固件类型

• 返回数据：返回数据为Boolean，表示是否发送成功
• 错误码：返回超时

注意事项： 1.部分信息来自固件请求任务的信息中，如当前固件的版本号、识别码 2.固件文件下载地址为内网可访问的URL，并且必须为完整的文件下载地址 3.此任务只能确认指令是否发送成功，暂时无法确保指令送达

五、Relevant Class

以下为此类中的关联类或内部类

1、XLinkSendDataPolicy

数据通讯策略

字段名	说明
AUTO	自动选择发送数据通讯，根据 RTT （往返时延）选择通道，通常情况下内网已连接时会选择选择内网通讯
LOCAL_ONLY	只尝试从内网发送
CLOUD_ONLY	只尝试从外网发送
LOCAL_FIRST	尝试从内网发送，失败则尝试外网发送
CLOUD_FIRST	尝试从外网发送，失败则尝试从内网发送

2、XLinkRestfulEnum.UserSource

用户登录来源

字段名	说明
WEB	网页登录
ANDROID	android客户端登录
IOS	ios客户端登录
WEIXIN	微信登录
QQ	QQ登录
WEIBO	微博登录
FACEBOOK	fackbook登录
TWITTER	twitter登录
OTHER	其它第三方平台登录

3、XLinkRestfulEnum.ShareMode

分享模式

字段名	说明
ACCOUNT	通过用户ID分享
QR_CODE	二维码方式分享
EMAIL	邮件方式分享

4、XLinkRestfulEnum.DeviceAuthority

设备控制权限

字段名	说明
R	只读
W	只写
RW	可读写
HID	取消权限，对成员取消设备的权限后，成员不再允许使用该设备，自v6.2.7.10版本起（以云端提供功能为准）

5、XLinkHandleShareDeviceTask.Action

设备分享操作

字段名	说明
ACCEPT	接受分享
DENY	拒绝分享
CANCEL	取消分享操作
DELETE	删除分享消息
ACCEPT_QRCODE	接收二维码

XDevice

设备对象类，SDK 中使用同时也提供给开发者使用的设备对象类。该类包括了设备的基本属性及部分相关方法。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

1、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
XDevice.State	枚举类	设备状态，见下文
XDevice.Event	枚举类	设备事件，见下文

2、Field

以下为此类中的常用字段及说明。

2.1、Attributes

由于设备对象包含的属性较多，不一一罗列其属性的getter/setter方法，以下字段都支持对应的方法，方法列表中不再赘述。大部分情况下，以下属性为仅读属性

字段名	字段类型	getter支持返回null	说明
macAddress	String	否	设备 mac 地址
productId	String	否	设备产品ID
deviceTag	String	否	设备标识
protocolVersion	byte	-	设备版本号，注意该值不一定有效，可能为0
bound	boolean	-	设备是否已与 APP 建立连接配对过
deviceId	int	-	设备ID
deviceName	String	是	设备名称，该值为保存到云端的数据，可能为 null
active	boolean	-	设备是否已经激活
isDeviceConnectedCloud	boolean	-	设备是否已经连接到云端服务器
lastLogin	String	是	设备最后一次登录日期，2018-06-01T19:45:28.417Z
activeDate	String	是	设备激活日期，2018-05-29T11:19:40.752Z
activeCode	String	是	激活码
authorizeCode	String	是	认证码
mcuMod	String	是	mcu 型号
mcuVersion	String	是	mcu 版本号
firmwareMod	String	是	固件型号
firmwareVersion	String	是	固件版本号
role	int	-	用户与设备的订阅关系，见下文
authority	String	否	设备访问权限，见下文
SN	String	是	设备序列号
subscriptionSource	int	-	设备订阅来源，见下文
subscriptionDate	String	是	设备订阅日期，2018-06-01T19:45:28.417Z
softInitDate	String	是	设备销售日期，2018-06-01T19:45:28.417Z

2.2、Role

用户与设备的订阅关系

字段名	字段类型	值	说明
ADMIN	int	0	用户为设备管理员
USER	int	1	用户为普通设备使用者

2.3、Authority

设备的控制权限或访问权限

字段名	字段类型	值	说明
R	String	R	可读
W	String	W	可写
RW	String	RW	可读写

2.4、SubscriptionSource

产生订阅关系的来源

字段名	字段类型	值	说明
UNKNOWN	int	0	未知来源
OUTER_NET_SCAN	int	1	外网扫描
USER_SHARE	int	2	其他用户分享
QR_CODE	int	3	二维码订阅
HOME_FAMILY	int	4	Home家庭
MANUALLY_ADD	int	5	用户手动添加设备
WECHAT_PUBLIC	int	6	微信公众号同步

3、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

3.1、construtor

public XDevice()

• 方法说明：

默认无参构造方法，通过此方法创建的设备对象不存在 mac 与 pid

public XDevice(@NotNull String json) throws IllegalArgumentException

• 方法说明：

通过 json 字符串反序列化创建设备对象，此方法用于将序列化为 json 字符串后的设备对象还原。注意还原的设备对象必然是丢失了一部分数据或者是存在部分数据状态不准确的情况（在序列化与反序列化时间间隔足够长的情况下），通常仅用于持久化或者传输设备对象。

• 参数说明：

参数名	类型	说明
json	String	设备序列化的 json 字符串，不允许为 null
exception	IllegalArgumentException	当反序列化失败时，抛出异常信息

3.2、toJson

@NotNull
public String toJson()

• 方法说明：

将设备对象序列化成 json 字符串

• 返回值：String，json 字符串；返回设备的序列化 json 字符串，不为 null

4、Relevant Class

以下为此类中的关联类或内部类，包括了设备状态与设备事件枚举类

4.1、XDevice.State

字段名	说明
DETACHED	XDevice的状态未知
DISCONNECTED	SDK设备与设备失去连接
CONNECTING	SDK正在连接设备
CONNECTED	SDK设备保持连接

当前当设备状态未知或设备不存在时，默认都返回 DISCONNECTED

4.2、XDevice.Event

字段名	说明
字段名	说明
SUBSCRIBE	订阅关系建立
UNSUBSCRIBE	订阅关系解除
INFO	设备基本属性变化
PROPERTY	设备扩展属性变化

设备事件在全局的设备监听回调中，设备变更时会有相应的事件，请参考参考设备管理对象关联接口 XLinkDeviceStateListener.onDeviceChanged

5、Addendum

设备对象的 json 序列化结构：

{
  "subscribe_date": "2018-06-01T19:45:28.417Z",
  "is_active": true,
  "role": "0",
  "last_login": "2018-06-04T20:49:37.78Z",
  "firmware_mod": "1",
  "active_code": "XXX",
  "active_date": "2018-05-29T11:19:40.752Z",
  "is_online": false,
  "mcu_version": "1",
  "firmware_version": "3",
  "source": "1",
  "pairing_id": "XXX",
  "mac": "ABC001",
  "soft_init_date": "",
  "pairing_key": "xxx",
  "mcu_mod": "1",
  "product_id": "xxx",
  "authority": "RW",
  "name": "",
  "authorize_code": "xxx",
  "id": "xxx",
  "sn": ""
}

XLinkConfig.Builder

配置信息的构建类，该类用于创建 SDK 的配置信息；最终生成的配置信息类为 XLinkConfig。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

1.1. Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
XLinkConfig	实体类	配置信息类，见下文
BaseLog.Config	实体类	输出日志配置类，详情请参考API-BaseLog.Config
CrashInfoProviderable	接口	崩溃环境信息收集接口，见下文
NetworkClientProcessor	接口	网络客户端配置接口，见下文
SSLFactoryProviderable	接口	SSL 配置接口，见下文
XLinkCloudListener	接口	云端回调监听接口，见下文
XLinkUserListener	接口	用户登录状态回调监听接口，见下文
XLinkDeviceStateListener	接口	设备状态回调监听接口，见下文
XLinkDeviceEventListener	接口	设备事件回调监听接口，见下文
XLinkDataListener	接口	数据端点回调监听接口，见下文
XLinkUser	实体类	用户信息类，详情参考API-XLinkUser
XLinkSendDataPolicy	枚举类	数据通讯策略，见下文
PluginTypeEnum	枚举类	插件类型，见下文

1.2. Field

以下为此类中的常用字段及说明。

1.2.1. Attributes

由于此类包含的属性较多，不一一罗列其属性的getter/setter方法，以下字段都支持对应的方法，方法列表中不再赘述。大部分情况下，以下属性为仅读属性

对于 XLinkConfig 配置信息来说，创建时使用的是相应的构建对象 XLinkConfig.Builder，通过 XLinkConfig 可以获取到相关的属性或者字段，但仅可读；所有字段与 XLinkConfig.Builder 保持一致，以下为 XLinkConfig.Builder 的字段与说明。

字段名	字段类型	getter支持返回null	说明
debug	boolean	-	是否开启 Restful 日志输出
logConfig	BaseLog.Config	否	SDK 日志输出配置类
autoDumpCrash	boolean	-	是否收集崩溃信息并存储到文件中
crashInfoProvider	CrashInfoProviderable	是	收集崩溃环境信息接口，设置收集崩溃信息时必须设置此参数
authResource	String	是	登录源，标识用户登录来源
mqttClientVersion	int	-	连接CM服务器的版本号
cloudServerUrl	String	否	CM 服务器地址
cloudServerPort	int	-	CM 服务器端口
apiServerUrl	String	否	http 服务器地址
apiServerPort	int	-	http 服务器端口
enableSSL	boolean	-	是否启用 SSL 验证
enableDebugMqtt	boolean	-	是否启用 MQTT 数据日志输出
enableDebugGateway	boolean	-	是否启用 MQTT 通讯日志输出
enabledLocalNetworkAutoConnection	boolean	-	是否启用内网自动连接功能
protocolVersionSupportedFlags	int	-	支持的协议版本
networkClientProcessor	NetworkClientProcessor	是	网络客户端的初始化接口
sslFactoryProvider	SSLFactoryProviderable	是	SSL socket 构建对象接口
cloudListener	XLinkCloudListener	是	云端回调监听接口
userListener	XLinkUserListener	是	用户登录状态监听接口
deviceStateListener	XLinkDeviceStateListener	是	设备回调监听接口
eventListener	XLinkDeviceEventListener	是	设备事件监听接口
dataListener	XLinkDataListener	是	数据端点回调监听接口
sendDataPolicy	XLinkSendDataPolicy	否	通讯策略

1.2.2. ProtocolVersionFlags

协议类型 flags

字段名	类型	值	说明
FLAG_PROTOCOL_VERSION_V5	int	0B0001	v5 协议版本
FLAG_PROTOCOL_VERSION_V6	int	0B0010	v6 协议版本

1.3. Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

如上所述，XLinkConfig 配置信息的构建由构建类实现，本身提供的getter方法与 XLinkConfig.Builder 保持一致，以下将介绍构建类的相应方法，XLinkConfig 对应的读取方法不再赘述

以下方法为 XLinkConfig.Builder 构建类的方法

1.3.1. withBuilder

public B withBuilder(BaseBuilder builder)

• 方法说明：

使用其它 Builder 构建一个新 Builder ，该方法允许拷贝其它 Builder 的配置信息

• 参数说明：

参数名	类型	说明
builder	BaseBuilder	基础构建类，该类是 XLinkConfig.Builder 的基类，处理通用的一些配置信息配置

• 返回值：B，泛型 BaseBuilder 类型；返回值为 BaseBuilder 的子类型，此处返回 XLinkConfig.Builder，返回当前 Buidler 对象

1.3.2. withXlinkConfig

public B withXlinkConfig(XLinkConfig config)

• 方法说明：

使用其它 XLinkConfig 构建一个新的 Builder，该方法允许拷贝其它 XLinkConfig 的配置信息

• 参数说明：

参数名	类型	说明
config	XLinkConfig	配置信息类

• 返回值：同上所述，当前 Builder 对象

1.3.3. setDebug

public B setDebug(boolean debug)

• 方法说明：

设置是否为 debug 模式，debug 模式下将输出日志，目前仅用于 Restful 日志的输出

• 参数说明：

参数名	类型	说明
debug	boolean	是否设置为 debug 模式以输出 Restful 日志，默认值为 false

• 返回值：同上所述

1.3.4. setLogConfig

public B setLogConfig(BaseLog.Config config)

• 方法说明：

设置日志输出配置信息，该日志为 SDK 内部输出日志，建议在任何情况下都进行配置，否则无法查看日志输出

• 参数说明：

参数名	类型	说明
config	BaseLog.Config	日志配置类，用于配置日志信息，见下文

• 返回值：同上所述

1.3.5. setAutoDumpCrash

public B setAutoDumpCrash(boolean autoDumpCrash)

• 方法说明：

设置是否自动转存异常崩溃信息，注意该功能开启时，必须设置崩溃信息提供对象，用于收集崩溃环境信息并存储到文件中；且该功能要求允许设备开启存储权限，否则无法正常使用；

若已集成第三方崩溃信息收集库，则建议关闭此功能，否则可能造成一些冲突问题。详情请参考FAQ

• 参数说明：

参数名	类型	说明
autoDumpCrash	boolean	是否自动转存崩溃信息

• 返回值：同上所述

1.3.6. setCrashInfoProviderable

public B setCrashInfoProviderable(CrashInfoProviderable providerable)

• 方法说明：

设置崩溃环境信息提供对象，当 SDK 运行期间捕获崩溃信息时，将崩溃信息保存到文本中时，将通过此信息提供对象收集当前崩溃环境的信息，并记录到崩溃日志中；注意设置了此崩溃环境信息提供对象不意味着已开启了崩溃信息收集功能，相应功能开启请参考方法进阶篇-SDK高级配置

• 参数说明：

参数名	类型	说明
providerable	CrashInfoProviderable	崩溃环境信息提供接口，该接口提供了若干方法以收集当前崩溃环境信息，见下文

• 返回值：同上所述

1.3.7. setCloudServer

public B setCloudServer(String url, int port)

• 方法说明：

设置云端服务器连接地址与端口，注意这里的云端服务器并不是指 http 服务器，而是 CM 服务器，该服务器用于连接设备与 SDK 通讯，使用 MQTT 协议进行通讯；默认值为公有云的正式环境地址及端口号

• 参数说明：

参数名	类型	说明
url	String	CM 服务器地址，默认值为 mqtt.xlink.cn
port	int	CM 服务器端口，默认值为 1884

• 返回值：同上所述

1.3.8. setEnableSSL

public B setEnableSSL(boolean enableSSL)

• 方法说明：

设置当前使用的 CM 服务器是否启用 SSL 验证通讯，注意此配置仅对 CM 服务器有效，不针对 http 服务器，默认情况下为开启，true

• 参数说明：

参数名	类型	说明
enableSSL	boolean	是否启用 SSL 验证通讯，默认值为 true，默认对应公有云服务器地址 mqtt.xlink.cn及端口 1884

• 返回值：同上所述

1.3.9. setApiServer

public B setApiServer(String url, int port)

• 方法说明：

设置 http 服务器的地址与端口号

• 参数说明：

参数名	类型	说明
url	String	http 服务器地址
port	int	http 服务器端口号

• 返回值：同上所述

1.3.10. setXLinkCloudListener

public B setXLinkCloudListener(XLinkCloudListener XLinkCloudListener)

• 方法说明：

设置全局的云端监听接口，包括了 CM 服务器的连接状态回调及事件通知。详情请参考进阶篇-云端消息推送

• 参数说明：

参数名	类型	说明
XLinkCloudListener	XLinkCloudListener	云端监听接口，见下文

• 返回值：同上所述

1.3.11. setDataListener

public B setDataListener(XLinkDataListener dataListener)

• 方法说明：

设置全局的数据端点监听回调接口，数据端点的变更通知都是通过此接口回调，当设备上报数据端点变更时，将通过此接口回调通知数据发生变更

• 参数说明：

参数名	类型	说明
dataListener	XLinkDataListener	数据端点监听接口，见下文

• 返回值：同上所述

1.3.12. setUserListener

public B setUserListener(XLinkUserListener userListener)

• 方法说明：

设置全局用户登录状态监听回调接口，当用户登录状态发生变更时，将通过此接口回调通知用户状态变更

• 参数说明：

参数名	类型	说明
userListener	XLinkUserListener	用户登录状态监听接口，见下文

• 返回值：同上所述

1.3.13. setDeviceStateListener

public B setDeviceStateListener(XLinkDeviceStateListener deviceStateListener)

• 方法说明：

设备状态监听回调接口，当设备状态变更或设备事件发生时，将通过此接口进行回调通知，详情请参考进阶篇-设备连接状态管理及进阶篇-设备订阅关系管理

• 参数说明：

参数名	类型	说明
deviceStateListener	XLinkDeviceStateListener

• 返回值：同上所述

1.3.14. setEventListener-自v6.2.6.x版本起

public B setUserListener(XLinkUserListener userListener)

• 方法说明：

设备事件监听事件，用于设备发送事件通知到 APP，设备事件请参考 API-XLinkDeviceEvent

• 参数说明：

参数名	类型	说明
eventListener	XLinkDeviceEventListener

• 返回值：同上所述

1.3.15. setSendDataPolicy

public B setSendDataPolicy(XLinkSendDataPolicy sendDataPolicy)

• 方法说明：

设置全局数据通讯策略，对于某些与设备的数据通讯，如获取数据端点及设置数据端点等，当与设备同处一局域网中时，可以通过内网通讯直接与设备进行信息交互；也可以通过外网（即 CM 服务器转发）进行数据信息交互；

前者更适用于外网环境差或无外网环境情况，后者更适用于远距离通讯及跨网通讯；这里的通讯策略即是指可以通过配置通讯方式的优先顺序从而选择不同的通讯方式以达到预期的目的。通讯策略与设备的连接状态相关联，在设备连接状态中区分了内网连接与云端连接两种不同的连接状态，该状态会影响到相应的通讯策略。

此通讯策略为全局的策略，针对具体的任务实际上也是支持任务设置临时的通讯策略以降低全局策略的限制，临时通讯策略优先于全局通讯策略，当不进行设置时默认使用全局通讯策略

XLinkGetDataPointTask.newBuilder()
    //针对具体的任务允许设置临时的通讯策略，该通讯策略优先于全局通讯策略
    .setSendPolicy(XLinkSendPolicy.CLOUD_FIRST)
    ...
    .build();

• 参数说明：

参数名	类型	说明
sendDataPolicy	XLinkSendDataPolicy	通讯策略，见下文

• 返回值：同上所述

1.3.16. setXLinkUser

public B setXLinkUser(XLinkUser user)

• 方法说明：

设置初始化的用户信息，用于快捷登录。在登录后用户信息允许开发者自行缓存，并且在下一次初始化 SDK 时提供，则会复用该用户信息而不需要强制再将进行用户登录以获取用户信息，详情请参考进阶篇-用户授权管理

• 参数说明：

参数名	类型	说明
user	XLinkUser	用户信息，请参考API-XLinkUser

• 返回值：同上所述

1.3.17. setDebugGateway

public B setDebugGateway(boolean enable)

• 方法说明：

设置是否开启内部通讯细节的转发日志输出，该日志涉及了内部 MQTT 通讯时的一些通讯日志，主要用于调试和分析问题；正常情况下不需要开启，开启该功能会导致输出日志信息大量增加，造成日志内容庞大冗余；建议仅在需要详情分析通讯流程或者是技术支持人员建议开启以辅助分析问题时才开启，默认情况下不开启

• 参数说明：

参数名	类型	说明
enable	boolean	是否输出当前通讯日志是否，默认值 false

• 返回值：同上所述

1.3.18. setDebugMqtt

public B setDebugMqtt(boolean enable)

• 方法说明：

设置 MQTT 通讯数据日志是否输出，此处的日志与上述的setDebugGateway(boolean)是存在差异性的，此方法开启的调试日志信息相对轻量级并且主要只关注了通讯的数据，而不会在日志中输出通讯的流程和细节；

正常情况下可以不开启，需要调试或分析日志信息时，建议开启，默认不开启

• 参数说明：

参数名	类型	说明
enable	boolean	是否开启 MQTT 通讯数据日志，默认值 false

• 返回值：同上所述

1.3.19. setAuthResource

public B setAuthResource(String value)

• 方法说明：

设置用户的登录源信息，当同一用户使用不同的登录登录时，将视为“不同的用户”但是共享相同的信息；即在该情况下即使用户重复登录也不会被强制下线；

登录源仅允许最大长度为16字符，支持大小写字母及数字，不支持空格及其它特殊字符，关于登录源详情可参考进阶篇-用户授权管理

• 参数说明：

参数名	类型	说明
value	String	登录源

• 返回值：同上所述

1.3.20. setMQTTClientVersion-自v6.2.6.x版本起

public B setAuthResource(String value)

• 方法说明：

设置连接 CM 服务器的版本号，默认版本号为3。在公有云环境和其它企业环境中， CM 服务器的版本号可能不同，其中高版本兼容低版本，但是低版本不支持使用高版本号连接。 不同版本号的 CM 服务器基础功能并无差异，高版本 CM 服务器可能支持新的功能。

• 参数说明：

参数名	类型	说明
value	int	连接 CM 服务器的版本号

• 返回值：同上所述

1.3.21. setLocalNetworkAutoConnection-自v6.2版本起

public B setLocalNetworkAutoConnection(boolean autoConnection)

• 方法说明：

设置是否默认开启内网自动连接功能，开启该功能的情况下，在同步设备列表之后及添加设备之后，默认会自动进行设备内网扫描并连接到设备，默认生效范围为所有设备

1. 该功能自 v6.2 版本以后生效
2. 该功能默认不开启
3. 开启该功能可能在内网设备连接与查找过程中导致内网通讯拥塞，造成扫描设备成功率降低，但在设备连接与通讯中会提高一定的稳定性
4. 非必须内网通讯的情况下不建议开启
5. 仅个别设备要求内网自动连接时，可单独设置，详情参考进阶篇-设备连接状态管理及相应API-XLinkDeviceManager

//单独设置某个设备自动连接
//处理方式有多种，以下仅为其中一种实现
XLinkDeviceManager.getInstance().connectDevice(
    device,
    XLinkConstant.FLAG_POLICY_LOCAL_AUTO_CONNECTION|XLinkConstant.FLAG_POLICY_CLOUD_AUTO_CONNECTION
);

• 参数说明：

参数名	类型	说明
autoConnection	boolean	是否开启内网自动连接功能，默认值为 false

• 返回值：同上所述

1.3.22. setProtocolVersionSupportedFlags-自v6.2版本起

public B setProtocolVersionSupportedFlags(int flag)

• 方法说明：

设置当前支持的协议版本号，该功能自 v6.2 版本以后生效，支持多 flag 配置如：setProtocolVersionSupportedFlags(flag1|flag2)

• 参数说明：

参数名	类型	说明
flag	int	flag 来自 XLinkConstant，目前存在 v5/v6 两个版本可选

• 返回值：同上所述

1.3.23. setNetworkClientProcessor

public B setNetworkClientProcessor(NetworkClientProcessor processor)

• 方法说明：

设置网络 client 初始化时二次处理的接口，由于内部分使用了 okhttpClient 进行网络通讯，实际上此处的网络通讯即是针对 okhttpClient 提供给开发者进行一些自定义处理，如设置某些自定义的 interceptor

• 参数说明：

参数名	类型	说明
processor	NetworkClientProcessor	网络请求客户端的处理接口，见下文

• 返回值：同上所述

1.3.24. setSSLFactoryProvider

public B setSSLFactoryProvider(SSLFactoryProviderable provider)

• 方法说明：

设置 SSL socket 创建工厂类，用于支持 CM 服务器的自定义 SSL 证书验证。根据不同的需求可能某些服务器要求使用其它 SSL 证书，则需要配置相关的验证处理

• 参数说明：

参数名	类型	说明
provider	SSLFactoryProviderable	SSL socket 创建工厂接口，见下文

• 返回值：同上所述

1.3.25. setPluginId

public B setPluginId(PluginTypeEnum type, String accessToken)

• 方法说明：

设置 pluginId 配置，插件配置用于 Restful 接口功能中使用，接口区分普通 openAPI 的接口，还有其它信息特定功能的 API 接口

• 参数说明：

参数名	类型	说明
type	PluginTypeEnum	插件类型，见下文
accessToken	String	插件 API 接口的 token

• 返回值：同上所述

1.4. Relevant Class

以下为此类中的关联类或内部类

1.4.1. XLinkConfig

对于 XLinkConfig 来说，除了与构建类相应的读取方法之外，还有少数一些自身独有的方法，在此一并做出简介；以下方法为 XLinkConfig 的方法

public static XLinkConfig defaultConfig()

• 方法说明：

静态方法，使用默认的配置信息

• 返回值：XLinkConfig，SDK 配置对象；

注意事项：此方法中很多可选的配置信息都是未配置的，通常情况下不推荐使用此方法

public static Builder newBuilder()

• 方法说明：

静态方法，创建一个 XLinkConfig 的构建对象，用于构建配置信息

• 返回值：XLinkConfig.Builder，配置信息的构建对象；

1.4.2. CrashInfoProviderable

崩溃环境信息收集接口，该接口用于收集当前崩溃环境的信息，主要为当前系统信息或者是应用信息

String provideEnvironment();

• 方法说明：提供当前的运行环境信息

@NotNull
String provideCrashFileStoragePath();

• 方法说明：提供异常文件保存的路径

@Nullable
String provideCrashFileName(@NotNull String dateTime);

• 方法说明：提供异常文件的文件名
• 参数说明：

参数名	类型	说明
dateTime	String	当前崩溃发生时间，以yyyy-MM-dd HH:mm:ss SS的形式提供

• 返回值：String，文件存储名称；允许为 null，若文件名为空或空字符串时，使用当前时间加_crash作为默认文件名

1.4.3. NetworkClientProcessor

网络请求客户端的初始化二次处理，默认启动 SDK 时会初始化相应的 Restful 接口配置及网络请求客户端，但是某些情况下开发者需要进行一些调整，则可通过此接口进行处理

void processorClient(@NotNull OkHttpClient.Builder builder);

• 方法说明：提供网络请求客户端的一些自定义处理
• 参数说明：

参数名	类型	说明
builder	OkHttpClient.Builder	请求客户端的构建对象，该参数不为 null

1.4.4. SSLFactoryProviderable

SSL socket 工厂类创建的配置接口，用于提供某些服务器需要使用自定义 SSL 证书验证

@Nullable
SocketFactory getSSLFactory();

• 方法说明：提供 SSL socket 的创建对象
• 返回值：SocketFactory，socket 创建对象；用于创建 socket 通讯对象，允许配置 SSLSocketFactory，使用自定义的 SSL 证书验证

1.4.5. XLinkCloudListener

云端回调监听接口，详情请参考进阶篇-云端消息推送

void onCloudStateChanged(CloudConnectionState state);

• 方法说明：CM 服务器连接状态变更回调

void onEventNotify(EventNotify eventNotify);

• 方法说明：CM 服务器消息通知回调

1.4.6. XLinkUserListener

用户登录状态变更回调监听接口，详情请参考进阶篇-用户授权管理

void onUserLogout(LogoutReason reason);

• 方法说明：用户登录状态变更回调，退出登录的原因

1.4.7. XLinkDeviceStateListener

设备事件回调监听接口，详情请参考进阶篇-设备连接状态管理及进阶篇-设备订阅关系管理

void onDeviceStateChanged(XDevice xDevice, XDevice.State state);

• 方法说明：设备状态变更回调

void onDeviceChanged(XDevice xDevice, XDevice.Event event);

• 方法说明：设备事件回调

1.4.8. XLinkDeviceEventListener-自6.2.6.x版本起

设备事件回调监听接口，主要是处理来自设备的内网事件，用于内网固件升级

void onDeviceEventNotify(XDevice device,List<XLinkDeviceEvent> event, int from);

• 方法说明：设备事件回调

1.4.9. XLinkDataListener

数据端点变更回调监听接口，详情请参考进阶篇-设备物模型详解

void onDataPointUpdate(XDevice xDevice, List<XLinkDataPoint> list);

• 方法说明：设备上报数据端点变更时的回调

1.4.10. XLinkSendDataPolicy

通讯策略

字段名	说明
AUTO	自动选择通讯方式（通过内网或者云端），根据当前的连接状态，网络状态选择；当内网与云端状态良好时，一般优先使用内网通讯
LOCAL_ONLY	仅内网通讯，不管当前的连接状态与网络状态如何，都仅使用内网通讯，即使内网未连接成功
CLOUD_ONLY	仅云端通讯，不管当前的连接状态与网络状态如何，都仅使用云端通讯，即使内网未连接成功
LOCAL_FIRST	内网优先，在可选的情况下，尽量保证优先内网通讯，无法通讯时自动切换为云端通讯
CLOUD_FIRST	云端优先，在可选的情况下，尽量保证优先云端通讯，无法通讯时自动切换为内网通讯

注：

1. 通讯情况下，使用自动模式即可
2. 若设备主要依赖于云端通讯，推荐使用 云端优先模式
3. 可选择通讯类型的任务，都是允许设置临时通讯策略的，临时通讯策略优先级高于全局通讯策略

1.4.11. PluginTypeEnum

插件类型

字段名	说明
ENVIRONMENTAL	环境数据插件
FEEDBACK	用户反馈插件
OPERATE_MANAGER	运营位管理插件

注：插件类型详情请通过相关 API 接口文档了解

XLinkConstant

常量类，大部份的在 SDK 中使用到的常量都会在此类中

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法。

一、Field

以下为此类中的常用字段及说明

1.1、Connection Policy

连接策略字段

字段名	字段类型	值	说明
字段名	字段类型	值	说明
FLAG_POLICY_NONE_CONNECTION	int	0B0000	不进行任何连接
FLAG_POLICY_AUTO_CONNECTION	int	0B0011	内网/云端自动连接
FLAG_POLICY_LOCAL_AUTO_CONNECTION	int	0B0001	内网自动连接
FLAG_POLICY_LOCAL_ONCE_CONNECTION	int	0B0100	内网一次性连接
FLAG_POLICY_CLOUD_AUTO_CONNECTION	int	0B0010	云端自动连接
FLAG_POLICY_CLOUD_ONCE_CONNECTION	int	0B1000	云端一次性连接

1.2、DataPoint Source

数据端点来源标识

字段名	字段类型	值	说明
FROM_CLOUD	int	1	来源云端数据
FROM_LOCAL	int	-1	来源内网数据
FROM_UNKNOWN	int	0	来源未自

1.3、Supported Protocol Version

支持的设备版本号

字段名	字段类型	值	说明
FLAG_PROTOCOL_VERSION_V5	int	0B0001	支持协议版本 v5
FLAG_PROTOCOL_VERSION_V6	int	0B0010	支持协议版本 v6

XLinkTMLManager

物模型相关管理类，处理一些物模型的事件或操作。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

1、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

1.1、registerTMLReportEventsSubscription

public void registerTMLReportEventsSubscription(List<TMLEventRegisterHolder> holders, int channel)

• 方法说明

注册物模型上报事件的订阅信息，提供需要注册的事件信息及需要注册的渠道（本地或云端），SDK将会注册相关的事件主题并在事件上报时通过XLinkTMLEventListener回调通知外部，回调事件请参考XLinkConfig.Builder中相关的接口监听。注意如果需要同时监听本地与云端的事件，需要分开不同的channel进行注册。

1. ==注意事件注册时并不保证一定会注册成功，有可能是不合法的事件或者是不同法的设备信息导致的==。默认情况下，本地的注册一般都会成功（但是实际会不会收到事件由具体的环境而定，如果事件注册成功但是设备不在同一局域网中或设备不上报事件，依然不会有任何事件），云端注册取决于事件、设备合法性以前网络状态。
2. 注册的事件在云端断开后重连时会默认自动尝试重新注册，注册结果将在回调中返回
3. 一旦用户退出登录或者是SDK反初始化（重新初始化），所有的缓存数据会被清除掉，所有注册过的事件也会被清除掉
4. 事件允许反复注册（但注册成功时实际后面的注册操作都不会生效）

• 参数说明：

参数名	类型	说明
holders	List<TMLEventRegisterHolder>	需要注册订阅的事件信息
channel	int	注册的渠道信息来源是本地或云端，枚举信息以XLinkConstant中的渠道来源为准

对于TMLEventRegisterHolder参数，该参数的基本结构如下，该参数包含了设备信息（mac与产品ID），关联的事件名称。用于向SDK中注册某设备相关的事件。

class TMLEventRegisterHolder{
  public String getMac();
  public String getPid();
  public String getEventName();
}

• 示例说明：

//订阅多渠道的事件
List<TMLEventRegisterHolder> holders=xxx;
//本地监听事件
XLinkTMLManager.registerTMLReportEventsSubscription(holders,XLinkConstant.CHANNEL_LOCAL);
//云端监听事件
XLinkTMLManager.registerTMLReportEventsSubscription(holders,XLinkConstant.CHANNEL_CLOUD);

1.2、unregisterTMLReportEventsSubscription

public void unregisterTMLReportEventsSubscription(List<TMLEventRegisterHolder> holders, int channel)

• 方法说明

与registerTMLReportEventsSubscription方法作用相反，一般注册与反注册需要成对存在。

1.3、checkTMLReportEventIfSubscribed

public Collection<TMLEventRegisterHolder> checkTMLReportEventIfSubscribed(Collection<TMLEventRegisterHolder> holders, int channel);

• 方法说明：

给定事件注册对象列表，返回该列表中已经被注册的事件对象。用于判断某些事件是否已经被成功注册。此方法可以在注册状态回调时调用，确认事件是否有被注册成功，也可以在任意地方查询某个事件是否有被注册成功。

XLinkDeviceEvent

设备事件类，来自设备发送给 SDK 的事件，根据事件的类型可以识别不同的事件，需要将数据进行解析才能获取具体的事件对象。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

1、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
FirmwareUpgradeTaskRequest	实体类	固件升级任务请求，见下文
FirmwareReportUpgradeResult	实体类	固件升级上报结果，见下文
FirmwareReportVersion	实体类	固件上报版本号信息，见下文

2、Field

以下为此类中的常用字段及说明。

2.1、Attributes

由于设备对象包含的属性较多，不一一罗列其属性的getter/setter方法，以下字段都支持对应的方法，方法列表中不再赘述。大部分情况下，以下属性为仅读属性

字段名	字段类型	getter支持返回null	说明
type	int	-	事件类型
len	int	-	数据长度
value	byte[]	是	数据内容

2.2、type

事件类型常量定义在此类中

字段名	类型	意义
TYPE_FIRMWARE_CHECK_UPGRADE_TASK	int	检测升级任务事件类型
TYPE_FIRMWARE_REPORT_UPGRADE_RESULT	int	上报升级结果事件类型
TYPE_FIRMWARE_REPORT_VERSION	int	上报固件版本事件类型

3、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

3.1、construtor

public XLinkDeviceEvent(int type, int len, byte[] value)

• 方法说明：

正常情况下设备事件对象不会由开发者创建，均为 SDK 内网处理数据后创建并回调提供给外部使用。

3.2、parseFrame2DeviceEvent

@Nullable
public <T> T parseFrame2DeviceEvent(@NotNull Class<T> clazz)

• 方法说明：

将当前设备事件解析成有效的事件对象，事件对象类型需要由外部提供，开发者应该通过事件的类型判断当前事件需要解析的对象类。

//判断事件的类型，并解析其具体事件对象使用
if(event.type == TYPE_FIRMWARE_CHECK_UPGRADE_TASK){
    FirmwareUpgradeTaskRequest request = event.parseFrame2DeviceEvent(FirmwareUpgradeTaskRequest.class);
}

• 返回值：T，事件对象类型

4、Relevant Class

以下为此类中的关联类或内部类

4.1、FirmwareUpgradeTaskRequest

固件升级任务返回结果对象

字段名	类型	说明
firmwareType	byte	固件类型
currentVersion	short	当前固件版本号
identifyCode	int	标识码

4.2、FirmwareReportUpgradeResult

固件上报更新结果对象

字段名	类型	说明
code	byte	升级结果码
firmwareType	byte	固件类型
mod	byte	设备mod
currentVersion	short	当前固件版本号
originalVersion	short	升级前固件版本号
identifyCode	int	识别码
taskIdLen	short	任务ID长度
taskId	byte[]	任务ID

4.3、FirmwareReportVersion

固件上报版本号结果对象

字段名	类型	说明
firmwareCount	byte	固件版本数量，一个设备存在多个模组或MCU或多个识别码分区时可能会有多个，正常情况下为1个
firmwareFrames	list	固件信息列表

• FirmwareInfoFrame

字段名	类型	说明
firmwareType	byte	固件类型
mod	byte	设备mod
identifyCode	int	识别码
version	short	固件版本号

XLinkDeviceManager

XLinkDeviceManager是设备维护管理类，所有设备的状态维护都通过这个类进行管理维护。通过XLinkSyncDeviceListTask任务同步的设备列表，默认会将设备添加设备管理列表中进行状态维护。

在设备管理维护中，设备可同时存在内网连接与云端连接两种连接方式，设备管理类也提供了相应的方法以便进行连接方式的切换或者更新。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

一、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
XLinkConstant	常量类	所有常用的常量将存在于此类中，包括常用的flag和部分默认参数值，详情请查看API-XLinkConstant
XDevice	实体类	设备对象，SDK 中广泛使用的设备对象，详情请查看API-XDevice
XDevice.State	枚举类	设备状态，该类用于表示设备的连接状态，详情请查看API-XDevice中相关类

二、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

默认情况下，不推荐未列出的其它方法，即使是开放的方法，因为部分方法可能仅 SDK 内部使用。

1、addDeviceConnectionFlags

public boolean addDeviceConnectionFlags(String deviceTag, int flag)

• 方法说明：

向已在维护列表中的设备添加新的连接策略，不影响原有的连接策略，注意当添加策略为XLinkConstant.FLAG_POLICY_NONE_CONNECTION时并不会有任何变更

注意连接策略是以 flag 的形式存在，多个 flag 是允许进行同时进行设置处理的，如：

XLinkDeviceManager.getInstance().addDeviceConnectionFlags(
    devTag,
    XLinkConstant.FLAG_POLICY_LOCAL_AUTO_CONNECTION|XLinkConstant.FLAG_POLICY_CLOUD_AUTO_CONNECTION
)

• 参数说明：

参数名	类型	说明
deviceTag	String	设备连接标识
flag	int	连接策略flag，请参考常量类数据API-XLinkConstant

• 返回值：boolean，添加结果存在该设备并添加成功时，返回 true，否则返回 false

2、removeDeviceConnectionFlags

public boolean removeDeviceConnectionFlags(String deviceTag, int flag)

• 方法说明：

向已在维护列表中的设备移除掉指定的连接策略，注意当移除的策略为XLinkConstant.FLAG_POLICY_NONE_CONNECTION 时并不会有任何变更

• 参数说明：

参数名	类型	说明
deviceTag	String	设备连接标识
flag	int	连接策略flag

• 返回值：boolean，移除结果；存在该设备并移除成功时，返回 true,否则返回 false

3、setDeviceConnectionFlags

public boolean setDeviceConnectionFlags(String deviceTag, int flag)

• 方法说明：

向已在维护列表中的设备设置连接策略，将覆盖掉原来的连接策略

• 参数说明：

参数名	类型	说明
deviceTag	String	设备连接标识
flag	int	连接策略flag

• 返回值：boolean，设置结果存在该设备并设置成功时，返回 true,否则返回 false

4、getDeviceConnectionFlag

public int getDeviceConnectionFlag(String devTag)

• 方法说明：

获取设备的连接flag，用于标识该设备对象的连接策略

• 参数说明：

参数名	类型	说明
devTag	String	设备标识

• 返回值：int，连接策略；返回设备连接策略flag

5、connectDevice

public boolean connectDevice(XDevice device, int flag)

• 方法说明：

连接指定设备对象，指定连接策略进行连接，注意此处的连接策略会替换掉设备原有的连接策略

• 参数说明：

参数名	类型	说明
device	XDevice	设备对象
flag	int	连接策略flag

• 返回值：boolean，处理结果；设置存在返回 true，否则返回 false，注意返回 true 不表示设备已经连接成功，仅表示设备进行了连接处理

public boolean connectDevice(@NotNull String devTag, int flag)

• 方法说明：

连接指定设备对象，指定连接策略进行连接，若给定的设备标识不存在维护列表中，则不会进行连接

• 参数说明

参数名	类型	说明
devTag	String	设备标识，不允许为 null
flag	int	连接策略flag

• 返回值：设备存在时返回 true,否则返回 false

6、disconnectDeviceCloud

public boolean disconnectDeviceCloud(@NotNull String devTag)

• 方法说明：

断开设备的云端连接，此方法不会影响内网连接并且不会移除设备。注意如果需要移除设备应该使用XLinkRemoveDeviceTask而不应该直接调用此方法

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，不允许为 null

• 返回值：boolean，处理结果；若设备存在尝试进行处理返回 true, 否则返回 false, 注意返回 true 不代表着已经成功断开连接

7、disconnectDeviceLocal

public boolean disconnectDeviceLocal(@NotNull String devTag)

• 方法说明：

断开设备的内网连接，此方法不会影响云端连接并且不会移除设备。注意如果需要移除设备应该使用XLinkRemoveDeviceTask而不应该直接调用此方法

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，不允许为 null

• 返回值：boolean，处理结果；若设备存在尝试进行处理返回 true, 否则返回 false, 注意返回 true 不代表着已经成功断开连接

8、containsKey

public boolean containsKey(@Nullable String devTag)

• 方法说明：

检测设备管理列表中是否包括当前的设备

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：boolean，查找结果；若设备管理列表中包含此设备则返回 true，否则返回 false

9、getDevice

@Nullable
public XDevice getDevice(@Nullable String devTag)

• 方法说明：

获取当前设备标识对应的设备

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：XDevice，查找的设备对象；返回设备对象若设备管理列表中存在该设备，返回值可能为 null

10、removeDevice

@Nullable
public String removeDevice(XDevice item)

• 方法说明：

移除维护的设备对象，断开设备所有连接，清除设备数据

• 参数说明：

参数名	类型	说明
item	XDevice	设备对象

• 返回值：String，设备标识；当设备不为 null时，移除设备并返回设备标识，否则返回 null

11、removeDeviceByDevTag

@Nullable
public XDevice removeDeviceByDevTag(String devTag)

• 方法说明：

若该设备存在设备管理列表中，从设备管理列表中移除设备，断开设备所有连接并清除设备的数据

• 参数说明

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：XDevice，设备对象；当设备存在时，返回被移除的设备对象，当设备不存在时，返回 null；

12、getDeviceLocalState

@NotNull
public XDevice.State getDeviceLocalState(String devTag)

• 方法说明：

获取设备内网连接状态，若设备不存在时，返回 DISCONNECT

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：XDevice.State，设备状态；

13、getDeviceCloudState

@NotNull
public XDevice.State getDeviceLocalState(String devTag)

• 方法说明：

获取设备云端连接状态，若设备不存在时，返回 DISCONNECT

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：XDevice.State，设备状态；

14、getDeviceConnectedState

@NotNull
public XDevice.State getDeviceConnectedState(String devTag)

• 方法说明：

获取设备的连接状态，当内网或云端已连接时都返回 CONNECTED，当内网或云端任一处于连接中时都返回 CONNECTING，否则返回 DISCONNECT

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：XDevice.State，设备状态；

15、isDeviceConnected

public boolean isDeviceConnected(String deviceTag)

• 方法说明：

判断指定设备的连接状态是否为 CONNECTED

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：boolean，判断结果；若设备已连接返回 true，否则返回 false

16、isDeviceCloudConnected

public boolean isDeviceCloudConnected(String deviceTag)

• 方法说明：

判断指定设备的云端连接状态是否为 CONNECTED

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：boolean，判断结果；若设备云端状态为已连接返回 true，否则返回 false

17、isDeviceLocalConnected

public boolean isDeviceLocalConnected(String deviceTag)

• 方法说明：

判断指定设备的内网连接状态是否为 CONNECTED

• 参数说明：

参数名	类型	说明
devTag	String	设备标识，允许为 null

• 返回值：boolean，判断结果；若设备内网状态为已连接返回 true，否则返回 false

18、getDeviceFromMacAddress

@Nullable
public XDevice getDeviceFromMacAddress(String macAddress)

• 方法说明：

根据 mac 地址从设备管理列表中查找对应的设备，若查找不到返回 null

• 参数说明：

参数名	类型	说明
macAddress	String	设备 mac 地址

• 返回值：XDevice，设备对象；若参数为 null 或查找不到该设备，则返回 null

19、getDeviceFromDeviceId

@Nullable
public XDevice getDeviceFromDeviceId(int deviceId)

• 方法说明：

根据设备ID从设备管理列表中查找对应的设备，若查找不到返回 null

• 参数说明：

参数名	类型	说明
deviceId	int	设备id

• 返回值：XDevice，设备对象；若参数为 null 或查找不到该设备，则返回 null

20、addDeviceStateListener

public void addDeviceStateListener(XLinkDeviceStateListener listener)

• 方法说明：

添加设备状态监听回调，若参数为 null 则不会添加

• 参数说明：

参数名	类型	说明
listener	XLinkDeviceStateListener	设备状态监听回调

• 返回值：void

21、removeDeviceStateListener

public void removeDeviceStateListener(XLinkDeviceStateListener listener)

• 方法说明：

移除设备状态监听回调

• 参数说明：

参数名	类型	说明
listener	XLinkDeviceStateListener	设备状态监听回调

• 返回值：void

XLinkSDK

XLinkSDK是 SDK 的入口，SDK 相关的操作方法会在此类中定义，如 SDK 初始化、启动、停止或者是任务的执行等方法。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

三、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
XLinkConfig	实体类	SDK 配置信息对象，详情请查看API-XLinkConfig.Builder
XLinkUser	实体类	用户信息对象，详情请查看API-XLinkUser
XLinkUserManager	实体类	用户管理对象，详情请查看API-XLinkUserManager
XLinkDeviceManager	实体类	设备管理对象，详情请查看API-XLinkDeviceManager

四、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

默认情况下，不推荐未列出的其它方法，即使是开放的方法，因为部分方法可能仅 SDK 内部使用。

4.1、init

public static void init(XLinkConfig config)

• 方法说明

静态方法，使用 SDK 配置对象初始化 SDK，这是使用 SDK 的前提条件，SDK 只有初始化之后才能启动并正常使用，在 SDK 未进行初始化和启动时调用 SDK 相关的操作将会抛出异常。注意 SDK 应该只能初始化一次，如果进行多次初始化，目前并不会抛出异常，但是后续的初始化操作都将无效。不推荐使用

//注意尽管这里有SDK的初始化方法，但是在实际使用中，应该通过以下方式进行初始化，否则可能导致SDK无法正确使用到某些Android平台的特性，或者引起SDK异常
XLinkAndroidSDK.init(config);
 
//调用此方法后不再需要再调用其它初始化方法了

• 参数说明

参数名	类型	说明
config	XLinkConfig	SDK 初始化的配置信息，不允许为空

注意事项：初始化 SDK 时，应该使用XLinkAndroidSDK.init(config)

4.2、deinit——自v6.2版本起

public static void deinit()

• 方法说明

静态方法，自v6.2版本起支持，SDK 的反初始化方法，通过此方法可以终止 SDK 并且将当前 SDK 所有使用的配置清除和资源都释放，将 SDK 还原到未进行任何初始化时的状态，部分已初始化过的无状态数据将会保留。当需要切换 SDK 配置信息或者是完全终止并释放 SDK 占用的资源时，则可以使用调用此方法。

4.3、start

public static void start()

• 方法说明

静态方法，启动 SDK，初始化 SDK 时仅仅只是设置了配置信息，而实际上未运行任何 SDK 的操作或者后台功能。正常使用 SDK 的功能必须启动 SDK，包括任务执行、XLinkRestful相关封装接口的使用都需要在启动 SDK 之后才能使用。允许多次启动 SDK，不会有任何影响。

注意事项：请注意任何调用 SDK 的位置，特别是执行任务必须启动 SDK 之后才能使用。

4.4、stop

public static void stop()

• 方法说明

静态方法，停止 SDK，在启动 SDK 之后如果需要停止 SDK 的运行，则可以调用此方法。注意一旦停止了 SDK，则 SDK 的所有功能将不能再使用，如需要使用需要再次启动 SDK。调用此方法时，目前不会清除掉当前已登录的用户信息。

4.5、logoutAndStop

public static void logoutAndStop()

• 方法说明

静态方法，退出当前用户的登录状态，清除用户信息并停止 SDK 的运行。相当于停止 SDK 并清除掉用户信息。调用此方法时，如果设置了用户登录状态监听回调，则会接收到用户退出登录的事件。

4.6、isStarted

public static boolean isStarted()

• 方法说明

静态方法，判断当前 SDK 是否已经启动。

• 返回值：boolean，布尔值；若 SDK 已经启动返回 true，否则返回 false

4.7、isInitialized

public static boolean isInitialized()

• 方法说明

静态方法，判断当前 SDK 是否已经进行了初始化。由于 SDK 初始化操作不支持多次初始化，当多次初始化时会抛出异常信息，所以此方法可以用来确认 SDK 是否已初始化再确定是否需要进行初始化的处理。

• 返回值：boolean，布尔值；若 SDK 已经初始化返回 true，否则返回 false

4.8、startTask

public static void startTask(Task task)

• 方法说明

静态方法，执行一个 SDK 任务，任务不应该为空，若任务对象不存在，则不会执行任务操作。注意任务对象执行需要保证任务对象是刚初始化的状态，即任务未执行过的。每个任务仅允许执行一次。

• 参数说明

参数名	类型	说明
task	Task	任务对象，用于执行的任务。不应该为空，否则不进行执行任何操作

4.9、stopTask

public static void stopTask(Task task)

• 方法说明

静态方法，停止一个任务，当任务正在执行中时，通过此方法可以停止一个任务。任务停止时实际上是被取消掉执行，将返回任务取消的错误码。

参数名	类型	说明
task	Task	任务对象，需要停止的任务。任务对象不存在时不执行任务操作

4.10、getVersion

public static String getVersion()

• 方法说明

静态方法，获取当前 SDK 的版本号

• 返回值：String，SDK 版本号

4.11、connectCloud

public static void connectCloud()

• 方法说明

静态方法，手动连接云端。不推荐使用

注意事项： 1.调用此方法时，必须确保用户信息是有效的，否则无法正确连接到云端，可能会引起一些错误信息回调，如用户凭证过期 2.调用此方法时会先停止当前的云端连接，再重新进行云端的连接 3.正常情况下都不需要手动调用此方法，通过正常的登录任务和操作 SDK 会自行维护相关的云端连接

4.12、disconnectCloud

public static void disconnectCloud()

• 方法说明

静态方法，手动断开云端连接。此方法会断开当前的云端连接，会导致所有设备的云端通讯不再可用，用户相关的云端推送消息也将无法获取到。正常情况下都不需要手动调用此方法，SDK 会自行进行相关的维护工作。不推荐使用

4.13、getUser

@Nullable
public static XLinkUser getUser()

• 方法说明

静态方法，获取当前 SDK 维护的用户信息。推荐直接通过用户管理对象API-XLinkUserManager获取进行相关的用户信息操作，后续可能会废弃此方法

//推荐直接通过XLinkUserManager获取相关用户信息
XLinkUser user = XLinkUserManager.getInstance().getUser()

• 返回值：XLinkUser，用户信息对象；详情请参考API-XLinkUser

4.14、getDeviceManager

public static XLinkDeviceManager getDeviceManager()

• 方法说明

静态方法，获取当前 SDK 的设备管理对象。推荐直接通过设备管理对象API-XLinkDeviceManager执行相关设备操作，后续可能会废弃此方法

//直接获取设备管理对象
XLinkDeviceManager DevMgr = XLinkDeviceManager.getInstance();

• 返回值：XLinkDeviceManager，设备管理对象；详情请参考API-XLinkDeviceManager

4.15、getUserManager

public static XLinkUserManager getUserManager()

• 方法说明

静态方法，获取当前 SDK 的用户管理对象。推荐直接通过用户管理对象API-XLinkUserManager执行相关的用户操作，后续可能会废弃此方法

//直接获取用户管理对象
XLinkUserManager userMgr = XLinkUserManager.getInstance();

• 返回值：XLinkUserManager，用户管理对象；详情请参考API-XLinkUserManager

XLinkUser

用户信息类，SDK 中用于缓存登录后的用户信息的实体类，该类也可用于提供 SDK 初始化用户信息，用于快捷登录

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

一、Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
XLinkAuthProvider	接口	Restful 接口请求时获取配置参数接口
XLinkUserManager	实体类	用户信息管理类，详情请参考API-XLinkUserManager

二、Field

以下为此类中的常用字段及说明。

2.1、Attributes

由于此类包含的属性较多，不一一罗列其属性的getter/setter方法，以下字段都支持对应的方法，方法列表中不再赘述。大部分情况下，以下属性为仅读属性

字段名	字段类型	getter支持返回null	说明
accessToken	String	是	http 接口请求使用的 token，有效时默认为2小时，用户信息有效时不可能返回 null
refreshToken	String	是	token 的刷新凭证，此凭证不能直接用于 http 接口的请求，但是有效期较长14天，当 token 过期时可通过此凭证进行刷新获取新的可用的 token，用户信息有效是不可能返回 null
authString	String	是	CM 服务器登录的有效凭证，用户信息有效时不可能返回 null
expiredTime	int	-	token 的有效时间，单位秒
uid	int	-	用户唯一ID

三、Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

由于 XLinkUser 比较简单，相应的方法与上述的字段相对应，此处不再赘述

3.1、toJson

@NotNull
public String toJson()

• 方法说明：

将数据端点序列化为 json 字符串数据

• 返回值：String，json 字符串；序列化得到的 json 数据，不为 null

四、Relevant Class

以下为此类中的关联类或内部类

4.1、XLinkAuthProvider

Restful 接口请求时获取配置参数接口，在 Restful 配置中，将提供一个实现此接口的对象，当 Restful 请求需要某些权限性的参数时，即可从此接口对象中获取，通常情况下获取的都是用户请求权限参数

String getAccessToken();

• 方法说明：获取接口请求时需要的 token 凭证

String getRefreshToken();

• 方法说明：获取刷新 token 时的凭证。当请求的凭证不存在或者无效时，则获取当前用户的刷新凭证，使用刷新凭证刷新 token，更新有效时间及 token 信息以提供用户权限接口使用；当无刷新凭证或者是凭证过期时，则将返回 token 过期的错误

void setAccessToken(String token);

• 方法说明：保存用户请求权限 token，此方法一般为在使用刷新凭证获取到新的 token 之后回调此方法缓存新的 token

void setRefreshToken(String token);

• 方法说明：保存用户的刷新作证

void onReauthorization();

• 方法说明：需要重新登录的回调，当刷新凭证不存在或者是无效时，无法获取新的 token 用于请求接口时，则会回调此接口，通知用户需要进行再次登录

五、Addendum

用户信息对象的 json 序列化结构：

{
  "access_token": "xxx",
  "refresh_token": "xxx",
  "user_id": "10000",
  "expire_in": "0",
  "authorize": "xxxx"
}

XLinkUserManager

用户信息管理类，用于管理当前用户信息，及相关的一些监听接口。

1. 以下方法说明中明确提供不推荐使用的方法，即为不建议开发者调用或者是开发者不应该进行任何数据修改。
2. 以下文档中未提及的方法均属于不推荐使用的方法

1.1. Reference

以下为此类中关联的Class及相关说明

类名	类型	说明
XLinkUser	实体类	用户信息类，详情请参考API-XLinkUser
XLinkAuthProvider	接口	用户授权信息处理接口，详情查看API-XLinkUser相关类

1.2. Field

以下为此类中的常用字段及说明。

1.2.1. Attributes

由于此类包含的属性较多，不一一罗列其属性的getter/setter方法，以下字段都支持对应的方法，方法列表中不再赘述。大部分情况下，以下属性为仅读属性

字段名	字段类型	getter支持返回null	说明
user	XLinkUser	是	用户缓存信息，用户信息有效时不返回 null
listener	XLinkUserListener	是	用户登录状态变更回调接口

1.3. Methods

以下方法为开发过程常用的方法说明，参数说明及返回值说明。此处仅提供了推荐开发者使用及可能需要使用的方法，部分未列出方法请根据实际情况评估调用。

1.3.1. checkUserId

public static int checkUserId(int userId)

• 方法说明：

  静态方法

  ，检测提供的用户信息是否有效，若无效时，返回当前缓存的用户ID，

  注意当前的用户ID也可能是无效的ID，不一定是有效的。此方法不会通过云端进行用户ID的检测，仅本地缓存信息检测，检测原则是用户ID不可能为0或非负数。

  1. 若输入的用户ID为合法规则的用户ID，则会返回输入参数的用户ID；
  2. 若输入的用户ID为非法（如0），则返回 XAPP SDK 当前缓存的用户ID；

当前用户ID可能无效的原因是，该方法为静态方法，当不进行任何的登录操作时该方法也是可用的；此时本地不可能存在用户的缓存信息，自然也不可能返回有效的用户ID。建议此方法仅用于快速过滤或检测来自外部的用户ID参数是否为当前用户ID。

• 参数说明：

参数名	类型	说明
userId	int	用户ID

• 返回值：int，用户ID；返回当前用户的ID信息

1.3.2. getUser

public XLinkUser getUser()

• 方法说明：获取当前用户信息；除此方法外，XLinkUserManager 还同时提供了 XLinkUser 的所有方法，用于方便地直接获取当前用户信息的某些信息，XLinkUserManager 实现了 XLinkAuthProvider 接口
• 返回值：XLinkUser，用户信息；可能返回 null

1.3.3. setUser

public void setUser(XLinkUser user)

• 方法说明：设置用户对象；一般情况下都不应该使用此方法，如果在 SDK 运行期间强制更新用户信息时，可能会导致很多接口无法正常使用。不推荐使用

FAQ

本文档描述了在集成 XAPP SDK 过程当中可能遇到的相关问题和解决方法。

一、常见配置问题

1.1. 在哪儿下载 XAPP SDK?

请到下载页面下载 XAPP SDK ：资源下载

1.2. 如何获得PID(产品ID)和CropID(企业ID)?

一般情况,通过对平台的账号注册即可得到一个企业ID（CorpID），有了企业后台账号之后，可以添加企业的产品，每个产品会有对应的产品ID生成，即可得到产品ID（PID），详情请通过链接了解。

1.3. 如何使用 XAPP SDK 自带的崩溃信息收集功能？

详情说明请参考进阶篇-SDK高级配置中，崩溃日志处理章节。

1.4. 第三方崩溃收集工具好像不能使用了？

请查看是否开启了 XAPP SDK 的崩溃信息收集功能。崩溃信息收集实际上是利用了 Java 中UncaughtExceptionHandler进行收集处理，若第三方崩溃收集工具使用了类似的方式处理则可能导致被 XAPP SDK 覆盖而无法正常使用。

建议如果使用第三方崩溃收集工具时，不要开启 XAPP SDK 的崩溃信息收集功能。该功能为辅助性功能，所有的崩溃信息仅保存到本地，并且无相应的崩溃信息分析工具（通常第三方工具会有功能丰富的崩溃信息工具）。

1.5. 为什么无法在控制台查看到日志输出？

请确认使用 XAPP SDK 时配置了日志输出功能setLogConfig(config)，同时一般情况下可以使用XLinkAndroidSDK.defaultConfig(context)提供的默认日志配置，该配置将会输出所有 debug 等级的日志并将 XAPP SDK 日志保存到文件中。

当需要将文件路径输出到指定位置而不是默认位置，也可以通过简单修改相关的配置自定义日志输出地址。

一般情况下建议在 Android 环境中使用XLinkAndroidSDK.defaultConfig(context)提供的配置文件作为母版进行更改，此时不需要自行实现 Loggable 接口。

//直接使用 XLinkAndroidSDK.defaultLogConfig 创建的Cofnig进行配置修改
//不需要实现Loggable接口
BaseLog.Config newConfig = XLinkAndroidSDK.defaultLogConfig(this)
        .setDebugLevel(Loggable.ERROR)
        .setEnableLogFile(false)
        .setLogoutPath("xxx");

请注意默认 XAPP SDK 日志不会自动输出到 Android 环境中 logcat 控制台，如果使用完全自定义的日志配置（即直接创建一个BaseLog.Config对象进行配置），请务必设置setLoggable(loggable)，通过对 Loggable 接口的实现将日志输出到 logcat。

BaseLog.Config config = new BaseLog.Config()
        .setLoggable(new Loggable() {
            @Override
            public int log(int i, String s, String s1, Throwable throwable) {
                //根据日志等级输出对应等级日志到 logcat
                switch (i) {
                    case Loggable.DEBUG:
                        Log.d(s, s1);
                        break;
                    case Loggable.ERROR:
                        Log.e(s, s1);
                        break;
                    case Loggable.WARN:
                        Log.w(s, s1);
                        break;
                }
                return i;
            }
        });

详情说明请参考[进阶篇-SDK高级配置](A-进阶篇/A-XAPP SDK高级配置.md)中，日志信息处理章节

二、常见数据端点问题

2.1. 多个设备同时上报数据端点都会收到事件回调么？

在 XAPP SDK 初始化时配置了XLinkDataListener，该回调用于监听数据端点变更时通知。当多个设备同时发生了数据端点变更并进行了上报时，只要 XAPP SDK 与设备保持着云端连接或内网连接，设备变更的数据端点即会通知到 XAPP SDK，XAPP SDK 进行处理后即会通过回调通知相应的变更事件。

如果 XAPP SDK 是与云端连接着，设备上报能正常上报到云端时，云端能下发到 XAPP SDK 则会回调该方法；如果 XAPP SDK 是设备保持内网连接着，设备上报时设备能将数据正常发送给 XAPP SDK，则XAPP SDK会回调该方法；

2.2. 为什么获取数据端点不全？

获取数据端点不全（或为空）时，对于通过内网获取与外网获取原因是有差异的。

• 在内网获取时 由于数据端点此时来源为设备，即设备会直接提供本身的数据端点，所以如果设备本身不存在数据端点（如 MCU 未上报数据端点信息给 Wifi 模块），则设备的 Wifi 模块也无法返回数据端点信息；
• 在外网获取时 由于数据端点此时来源为云端，如果云端不存在缓存的数据端点信息时（如设备从未进行过上报数据给云端，云端也就不会有任何的缓存记录），则云端无法返回数据端点信息；

关于数据端点获取时，请留意以下情况：

1. 该数据端点是否产品一开始定义是存在的，还是后续添加的
2. 该数据数据端点是否为“虚拟数据端点”，即通过计算公式等方式产生的数据。如果是虚拟的数据端点，则直接通过设备获取时可能获取不到该数据端点，因为该数据端点只会在云端进行数据处理并更新信息。
3. 设备本身在激活后是否有上报过该数据端点，若有的话请确认一下是平台的数据端点值与设备的数据端点值是否相同。确认方式可以如下操作：
   1. 在设备在线时（必须确保设备在线），登录管理台并查找到该设备
   2. 查看设备详情页面下方“实时数据”，若无数据信息可配置选择需要检验的数据端点
   3. 查看数据端点值信息。若存在数据说明设备已经上报过，若暂无数据说明设备未上报过该数据

若设备未上报过数据端点，则通过云端方式获取不到未上报过的数据端点值。产品中的数据端点配置仅仅是一个数据端点模板，对于实际的设备来说，当设备未进行对应索引的数据端点上报过时，平台不会保存该索引的数据端点值（因为不知道该数据端点到底可能值是什么），所以获取数据端点时是不存在未上报过的数据端点值的。

若以上建议无法解决问题，请尝试以下操作：

1. 请将产品后台数据端点配置提供一下，并提供一下获取数据端点时输出的日志信息以确认该数据端点信息（注意若无法确认日志信息有效，也可以将 APP 开启到获取数据端点操作的完整日志一起提供，可以从日志中定位获取的数据端点模板信息是否正确有效，请开发人员根据应用过滤日志，避免大量系统日志），然后通过工单系统提出问题
2. 如提供日志时，请提供对应产品 PID/MAC 及预期需要的数据端点索引及其信息
3. 如果允许也可以直接提供企业 ID 与管理台账号信息，此方式更便于查找和发现问题

2.3. 为什么数据端点变更回调时，有时会没有设备模板信息？

关于数据端点的信息，数据端点的获取与更新实际上只会有数据端点的具体值和基本信息，数据端点的其它信息如描述等是由数据端点模板确定的。

XAPP SDK在默认情况下会去获取数据端点模板，但是该操作是异步的，并不会必须获取到模板的情况下才允许数据端点的获取与通知。所以当存在模板时，会使用模板信息更新数据；但是不存在模板时，数据端点仅会有基本数据。

模板功能为辅助功能，模板的使用在 XAPP SDK 中将尽可能保证有效，但无法确定任何时候都必然有效。如果需要确保数据端点模板任何时候都一定有效，建议自行进行模板信息维护。可通过XLinkGetDataPointMetaInfoTask任务获取到相关的产品的数据端点模板，详情请查看API-Task API

正常情况下，模板功能都是可用有效的，即使无效也仅会出现在最开始的时候，随着设备的使用只要该设备的模板不存在，XAPP SDK 都会在操作时尝试获取该设备的模板进行处理。

三、常见设备问题

3.1. 为什么扫描不到设备?

请按下述步骤进行排查：

• 设备是否跟 APP 在同一局域网内
• PID 设置是否正确
• 扫描超时是否设置过短（可能由于网络环境问题导致通讯不及时）
• 设备和 APP 的网络连接是否正常
• 使用 demo 进行扫描，对比结果
• 使用 IOS Demo 进行扫描，对比结果
• 使用 debug 模式开启 XAPP SDK ，查看具体日志
• 联系我们，提供相关操作或者日志信息(可以通过工单系统提出问题)

3.2. 为什么无法添加设备?

请按下述骤进行排查：

• 设备是否跟 APP 在同一局域网内
• 设备和 APP 的网络连接是否正常
• 登录管理后台确认设备是否正常上线
• 查看 onError 中返回的 errorCode 和异常信息
• 使用 debug 模式开启 XAPP SDK，查看具体日志
• 联系我们，提供相关的操作或者日志消息

3.3. 什么情况下会自动管理连接设备?

正常情况下，只要设备在维护列表中，即会对设备进行自动管理连接（包括云端连接与本地连接）。在以下情况下默认会将设备添加到设备维护列表中。

• 通过 XLinkSyncDeviceListTask 任务同步设备列表后设备将添加到维护列表中
• 通过 XLinkAddDeviceTask 添加订阅设备后设备将添加到维护列表中

部分情况下设备的本地连接是不一定需要的（如仅 Wi-Fi 使用的设备或 2G 设备），取决于某些操作是否有取消本地连接要求，可以进行连接管理方式的调整，默认情况下都会自动管理本地连接。

1. 当开发者使用 XLinkSyncDeviceListTask 获取设备列表成功时，如果设置了 setConnectLocal(true) ，XAPP SDK 自动对设备进行云端及本地连接。若设置不需要本地连接，则仅进行云端连接管理
2. 当开发者使用 XLinkAddDeviceTask 添加新设备成功后，同样可设置 setConnectLocal(false)，处理同上所述

注意事项：v6.2版本与之前版本的设备自动管理连接策略是不一样的，详情请参考进阶篇-设备连接状态管理

3.4. XAPP SDK 如何管理设备连接状态?

正常情况下，开发者不需要自行维护设备的连接状态，由 XAPP SDK 内部进行连接和处理;

开发者对设备状态有跟踪需求时,可以通过设置设备状态监听达到及时正确处理设备状态的目的

详情说明请参考进阶篇-设备连接状态管理

3.5. 如何在扫描设备时判断设备是否已经被订阅了？

出于安全问题考虑，目前并无可以查询设备是否已经订阅过的接口。建议处理方式为直接对该设备进行订阅操作，如果返回订阅失败则可以确定该设备被订阅过。

四、常见用户问题

4.1. 为什么一直无法登录成功？

在登录操作中，不仅是通过账号密码登录服务器成功获取到用户 API 调用凭证即可，由于实际应用中会与设备进行通讯，而设备的通讯方式不依赖于 API 的调用。因此用户登录成功还需要与云端服务器（CM 服务器）建立连接。

如果无法登录成功时，可能是未能正确登录 HTTP 服务器获取用户调用作证，也可能是未能正确与云端服务器建立连接。请确认一下以下注意事项：

1. APP 必须在网络通畅并能连接到外网的情况下才能登录成功，请确保 APP 可以正常使用外网。
2. 请留意 API 服务器地址及端口是否配置正确，默认情况下 https 域名端口号对应为 443，http 域名端口号对应为 80。
3. 请留意云端服务器地址及端口是否配置正确，使用公有云默认端口号为 1884，如果使用私有云地址，请自行确认使用的端口号。
4. 请留意是否需要开启 SSL 的验证，默认公有云使用 1884 端口时需要开启 SSL 验证，开启方式请参考配置。

XLinkConfig config = XLinkConfig.newBuilder()``  ``//true为开启SSL验证，false为不开启``  ``.setEnableSSL(``true``)``  ``...``  ``.build();``XLinkAndroidSDK.init(config);

1. 如果使用私有云环境，并配置了 SSL 证书验证，请注意添加 SSL 验证。

XLinkConfig config = XLinkConfig.newBuilder()``  ``.setSSLFactoryProvider(``new` `SSLFactoryProviderable() {``    ``@Override``    ``public` `SocketFactory getSSLFactory() {``      ``//配置自行处理的SSL验证的对象，用于云端服务器连接使用``      ``return` `socketFactory;``    ``}``  ``})``  ``.setNetworkClientProcessor(``new` `NetworkClientProcessor() {``    ``@Override``    ``public` `void` `processorClient(OkHttpClient.Builder builder) {``      ``//配置自行处理SSL验证的对象，用于http请求``      ``builder.sslSocketFactory(socketFactory，trustManager);``    ``}``  ``})``  ``...``  ``.build();``XLinkAndroidSDK.init(config);

4.2. 为什么账号被其它用户登录的情况下，启动 APP 会提示用户的 token 过期？

默认情况下同一时间同一账号不允许重复登录。该问题出现需要以下几个前提：

1. 使用快捷登录功能
2. APP 仅支持用户单点登录（即同一时间同一账号只能登录一次，不支持如多平台或多端登录）
3. 用户在 APP1 登录后退出 APP1，之后该账号在其它 APP 或使用其它方式登录过
4. 启动 APP 后立即进行快捷登录

当满足以上前提时，由于用户在其它地方已重新登录过，用户在 APP1 上原有的登录信息将失效，此时启动 APP1 将立即进行快捷登录，但是由于账号信息已经失效，因此将接收到 TOKEN_EXIPIRED 的错误。

如果需要为用户做自动登录，请注意处理好 token 过期的操作。该方式并不是踢掉用户，开发者可以自行处理为用户重新自动登录或者提示登录时间过长需要重新登录。请注意 token 是具有有效期的，如果长时间不登录（或者通过其它方式在其它地方进行了登录）必然会导致 token 过期。

注意：v6.2版本起强烈建议使用新的快捷登录方式，详情请参考进阶篇-用户授权管理

4.3. 什么情况下需要用户重新授权(登录)?

开发者应使用 XLinkUserAuthorizeTask 来进行用户授权（登录），只有用户授权后才能使用云端相关的功能（获取设备列表，云端连接等等）

如果 APP 已经保存了授权信息，那么在启动 XAPP SDK 时需提供（包装成 XLinkUser 对象传入），其后 XAPP SDK 启动后会自动进行授权管理。

快捷登录操作处理请参考进阶篇-用户授权管理快捷登录处理章节

未授权或者授权信息无效的情况下，开发者应主动调用 XLinkUserAuthorizeTask 进行授权，一般在登录页（Login/SignIn）进行。

4.4. 如果私有云环境使用了自签证书，需要如何处理？

如果使用私有云环境，并使用了自签证书，需要启用自定义的 SSL 验证，请通过以下方式添加 SSL 验证，更多详情可参考进阶篇-SDK高级配置

XLinkConfig config = XLinkConfig.newBuilder()``  ``.setSSLFactoryProvider(``new` `SSLFactoryProviderable() {``    ``@Override``    ``public` `SocketFactory getSSLFactory() {``      ``//配置自行处理的SSL验证的对象，用于云端服务器连接使用``      ``return` `socketFactory;``    ``}``  ``})``  ``.setNetworkClientProcessor(``new` `NetworkClientProcessor() {``    ``@Override``    ``public` `void` `processorClient(OkHttpClient.Builder builder) {``      ``//配置自行处理SSL验证的对象，用于http请求``      ``builder.sslSocketFactory(socketFactory，trustManager);``    ``}``  ``})``  ``...``  ``.build();``XLinkAndroidSDK.init(config);

4.5. 用户退出登录状态的原因有什么？

如果 Token 过期或者被同一账号踢下线，那么void onUserLogout(LogoutReason reason)会被调用。登出原因一般情况下有三种：

• 用户主动退出
• token 过期
• 用户账号被踢出

其中后两种登出原因要求用户应该重新进行登录操作，才能进行重新授权并使用XAPP SDK相关的功能。

注意事项：XAPP SDK 在 token 过期/账号踢出的情况下都会自动中止（即进行了 stop 操作），注意再次使用时需要启动 XAPP SDK ，详情请参考开发指南

详情说明请参考进阶篇-用户授权管理

4.6. XAPP SDK 中如何维护凭证（token） ？

请参考 进阶篇-用户授权管理 相关章节详细说明了用户凭证如何维护。

五、常见 API 问题

5.1. 错误码处理

错误码在v5版本与v6版本 XAPP SDK 中是不同的，v6 XAPP SDK 中的错误码将更加准确具体以及携带足够的信息用于辅助处理与分析。

1. 对于v5版本升级到v6版本中错误码的变更,请参考版本升级
2. 对于v6版本中错误码列表请参考[APP-SDK错误码](../5）APP SDK错误码.md)
3. 对于v6版本中新旧错误码的对照说明请参考API-错码说明与使用

六、其它问题（与 SDK 无关）

6.1. 为什么注册或修改密码邮件接收不到？

邮件发送是通过第三方邮件服务发送的，邮件是否能发送成功需要满足第三方邮件服务规则。通常有可能是发送人的格式存在问题（如部分邮件服务商不允许发送人携带如逗号、小数点等特殊符号），相关发件要求或规则可参考：邮件服务商规则

资源下载

一、下载

下载地址	版本号	发布时间	备注
v6.2.7.4_sdk	6.2.7.4	2019.04.03	使用此版本时，建议使用压缩包中的xlink_wrapper.jar替换旧的文件；该文件更新默认的日志文件输出路径
v6.2.3.7_sdk	6.2.3.4	2018.09.20	-
v6.1.0.3_sdk	6.1.0.3	2018.07.05	-
v6.0.7.1_sdk	6.0.7.1	2018.05.24	-
v6.0.6.9_sdk	6.0.6.9	2018.05.18	-

版本更新说明请参考相应版本的版本升级

二、版本更新记录

2.1、2019.04.03-v6.2.7.4

类别	更新内容
配置优化	1.新增支持配置连接CM服务端的版本号，支持不同环境下使用不同CM版本号 2.新增设备事件监听事件
任务更新	1.新增同步 Home 设备列表任务 2.新增内网固件升级功能相应任务
数据更新	1.新增设备对象云端在线可访问字段，更新设备连接状态查询方法 2.优化了设备操作接口
错误码	1.新增 SSL 异常错误码，由于 SSL 引起异常时将直接获取到该信息
资源优化	1.优化异常对象的数据存储，降低重复的操作及频繁申请内存问题 2.优化 token 无效时不再处理相应的任务，降低资源的占用
功能优化	1.更新扫描端口的使用，降低端口被其它网络程序拦截数据导致的无法扫描到设备的问题 2.优化日志输出配置，提供日志文件路径获取方法
接口更新	1.优化 Restful 接口的初始化时机，现在 XAPP SDK 初始化后即可正常使用 Restful 接口 2.新增阿里推送配置注册接口
BUG修复	1.修复设备管理资源释放后可能引用异常的问题 2.修复反复订阅已存在的设备时可能会订阅失败的问题 3.修复部分任务有时会返回不正确的错误码 4.修复在低版本 Android 系统中由于 JDK 版本问题引起的崩溃

2.2、2018.09.20-v6.2.3.7

类别	更新类型
配置优化	1.新增 XAPP SDK 反初始化，重置方法 2.新增支持的协议类型配置接口，优化数据通讯 3.新增内网自动连接配置接口，默认不开启 4.修正日志输出不转存到文件的情况下也允许输出到控制台
扫描优化	1.优化扫描任务，提高扫描结果的准确率及发现速度 2.优化扫描任务逻辑，提高扫描成功率 3.优化扫描操作，默认不开启设备内网自动扫描连接
订阅优化	1.修复订阅设备任务某些情况下不重试的问题，优化订阅任务流程 2.新增订阅设备方式
数据通讯	1.优化发送策略任务逻辑，修复任务某些情况下会尝试重试的问题 2.修复设备云端连接失败时，云端状态已断开时依然重试的问题 3.修复某些情况下云端断开时，未及时通知外部管理类状态变更的问题 4.优化设备上下线状态消息通知，提高准确性及响应速度
接口更新	1.新增短信登录的 restful 接口，新增用户注销接口 2.新增快捷登录任务 3.新增连接设备任务，新增连接策略 4.新增短信登录任务
资源优化	1.优化数据缓存，断开连接时清除缓存信息
其它	1.修正描述性文本错误

2.3、2018.07.05-v6.1.0.3

1. 更新API错误码,接口返回的错误码更加准确完整
2. 修复restful接口中json可能转换异常的问题
3. 修复添加V5设备时部分情况下未正确抛出失败错误码的问题
4. 新增基础数据对象(设备对象-XDevice,数据端点-XLinkDataPoint,用户信息-XLinkUser)统一的序列化与反序列化功能
5. 修复数据端点可能存在模板数据未正确更新的问题
6. 移除第三方json库的使用(与官方json库存在不兼容性),json处理集成到 XAPP SDK 公共库中
7. 修复发送策略任务可能导致数据收发失败的问题
8. 修复数据端点回调通知时未更新模板信息的问题
9. 修复错误码生成时可能未正确识别错误码的问题
10. 新增restful接口,第三方用户初始化手机并设置密码的接口
11. 修复restful接口中部分情况下资源释放不及时的问题
12. 优化设备信息获取流程,修复可能出现无法正确获取设备信息的问题
13. 修复某些情况下设备资源未及时释放的问题

2.4、2018.05.24-v6.0.7.1

1. 更新云端与本地连接管理,优化云端连接功能
2. 修复断开连接时部分缓存数据未正确清除的问题
3. 调整数据发送处理逻辑,根据发送策略更合理处理发送数据
4. 修正部分情况下设备状态未及时更新的问题
5. 其它性能优化和细节BUG修复

2.4、2018.05.18-v6.0.6.9

1. 更新部分设备管理功能,内部逻辑调整与优化
2. 新增多点登录等多个功能
3. 优化与设备通讯处理

三、Jar包更新方式

更新场景	更新方式
若 libs 文件中已存在相应的 jar 包(与替换包同名)	方式一: 请直接复制已下载的 XAPP SDK jar 包然后在项目的 libs 文件上(直接在 AS 中进行操作)右键→粘贴, 在弹出 jar 包替换提醒消息中, 选择Overwrite for all(一次性全部替换), 或者Overwrite(逐个选择替换) 方式二: 也可以先删除掉 libs 文件下需要替换的 jar 包, 再将新的 jar 包复制并粘贴到 libs 文件夹下即可
若 libs 文件中不存在相应的 jar 包	将新的 jar 包复制并粘贴到 libs 文件夹下即可

注意:

1. 在替换完 XAPP SDK 后,请务必确认是否已正常替换了 jar 包,(可通过检测 XAPP SDK 的版本号确认)
2. 使用“方式一”替换时,必须有弹出替换消息的弹窗才是正常的
3. 部分情况下存在无法正确替换,推荐使用“方式二”重新尝试, 如若还不能正常使用, 尝试关闭 AS 再重启

Demo下载

1.1. demo应用

下载地址	版本号	发布时间	更新说明
demo_apk	v6.2.7.13	2019.04.03	1.调整demo界面，更新大部分界面及重构部分功能，使demo更加方便易用 2.新增保存已使用过的产品ID及企业信息，方便重复使用 3.新增SDK相应功能测试
demo_apk	v6.2.3.12	2018.09.20	1.新增smarklink配网功能 2.同步更新 XAPP SDK 版本到6.2.3.7 3.更新部分配置功能
demo_apk	v6.2.0.4	2018.07.03	1.同步更新 XAPP SDK 版本到6.1.0.3 2.修复离线时设备无法分享的问题 3.更新测试环境API 4.调整XLinkDataPoint的引用（新版本变更内容）
demo_apk	v6.1.0.12	2018.05.24	1.同步更新 XAPP SDK 版本到6.0.7.1
demo_apk	v6.1.0.8	2018.05.18	1.新增API环境切换设置,切换环境不再需要重新编译 2.新增二维码扫描订阅设备功能 3.新增home相关功能 4.更新优化demo部分UI显示与实现逻辑

1.2. 项目源码

下载地址	版本号	发布时间	更新说明
demo_source	v6.2.7.13	2019.04.03	见同步更新的demo_apk
demo_source	v6.2.3.12	2018.09.20	见同步更新的demo_apk
demo_source	v6.2.0.4	2018.07.03	见同步更新的demo_apk
demo_source	v6.1.0.8	2018.05.18	见同步更新的demo_apk

1.2.1. 项目源码编译环境

• 自v6.2.7.x版本起，编译环境更新为

编译环境	说明
AS版本	3.3.2
gradle版本	3.3.2
其它	升级到AndroidX

• 旧版本编译环境

编译环境	说明
AS版本	3.0.1
gradle版本	4.1

请注意关于DEMO的一些事项:

• 该APK为调试版本APK
• demo默认为正式环境的API,若需要使用其它环境请在demo中切换
• 不同环境(如正式环境/测试环境)的账号无法互通,请注意
• 若安装后无法进入主界面,请确认是否开启存储权限及相机权限(v6.2版本DEMO后已进行权限申请处理)

2、说明文档

2.1. 概述

SDK_DEMO 是基于 XAPP SDK 实现的便于测试和验证的 DEMO 程序。其包含以下功能（自v6.2.7.13版本起）：

1. 用户登录
2. 动态的 XAPP SDK 配置
3. XAPP SDK 的使用（包括设备扫描、添加订阅、移除、控制、状态获取、设备连接等）
4. Home 相关操作（暂不包括 Room 操作）
5. 第三方推送快捷配置（包括 FCM 与阿里云）
6. 汉枫配网功能（集成自汉枫，与 XAPP SDK 本身无关联）
7. 二维码订阅设备、SN 订阅设备
8. 基础的 DEMO 信息（使用的 XAPP SDK 版本、当前登录的用户信息、DEMO 运行的日志信息、第三方推送消息的缓存记录）

2.2. 使用说明

所有功能都有自身的作用或目的，部分功能由于程序显示问题或描述问题无法在程序中以详细的提示文本说明清楚功能的作用，在这里指出部分功能的作用或如何使用。

2.2.1. 动态配置 XAPP SDK

DEMO 支持在启动程序时可以动态修改 XAPP SDK 配置或重新初始化；这一步是非常重要的。强烈建议参考开发指南中所有的配置项，这样会更加清楚该配置项的作用与目的。 以下仅列出部分重要的配置项及功能。

2.2.1.1. 私有云环境配置

1. 选择【自定义环境】
2. 输入【API 地址及端口号】；输入【CM 地址及端口号】；若不清楚使用的环境信息请咨询项目经理、对接人员或提交售后服务。
3. 若私有云环境有自签 SSL 证书，请选择【使用 SSL 证书】并选择证书文件，否则可能无法正确连接到相关服务器；（注意证书将用到 API 及 CM 服务器连接中）
4. 切换【CM 客户端版本号】，由于支持的设备版本及 XAPP SDK 版本更新，公有云环境默认支持版本3；若私有云环境未使用新的设备版本或更新到最新服务版本，请切换到版本2；

2.2.1.2. 内网自动连接（自 XAPP SDK v6.2.6.x 版本起）

1. 若设备不需要内网连接或通讯，仅通过云端操作，可以不勾选【内网自动连接】功能；以降低 XAPP SDK 资源占用及数据维护成本；不勾选内网自动连接的情况下，设备将会内网不在线。

2.2.1.3. 协议版本支持（自 XAPP SDK v6.2.6.x 版本起）

1. XAPP SDK 是同时兼容所有版本的 XMQTT 协议，包括了v5/v6版本的协议
2. 使用哪个类型的协议是取决于设备使用的协议版本，若设备使用了v5版本协议，则 XAPP SDK 需要使用v5协议版本；若设备使用了v6版本协议，则 XAPP SDK 需要使用v6版本协议；
3. 使用v6.x版本的设备，XAPP SDK 都需要使用v6版本的协议
4. 使用v6.2版本的设备，XAPP SDK 的【CM 客户端版本号】需要使用版本3

2.2.1.4. 登录源

登录源是用于标识当前用户的来源信息；如在 APP 中登录，可以将登录源设置为“APP”；在 TV 中登录，可以将登录源设置为“TV”；

1. 登录源允许为空
2. 登录源仅支持数字及26个字母，不能使用空格及特殊符号；最大长度为16个字符
3. 相同登录源（登录源字符完全匹配）的用户会互相强制下线，即同一时间仅允许同一登录源的用户存在；不同登录源的用户不受影响

2.2.1.5. 初始化及快捷登录

1. 当进行了任何的 XAPP SDK 配置修改后，需要生效则必须进行重新初始化；
2. 使用上一次的配置信息及用户信息直接快捷登录时，则不需要修改配置直接【快捷登录】即可；

2.2.2. DEMO 功能

配置功能是主要的对设备相关的操作，或者是 DEMO 中最常用的操作；在登录成功后进入程序主界面后下方的【配置】tab 即可。

2.2.2.1. 设备配网

设备配网功能目前集成自【汉枫】的 smartlink 配网功能，根据【汉枫】提供的 DEMO 修改引入程序中，方便对设备进行配网操作。

1. 仅用于【汉枫】模块的 smartlink 配网，不能用于其它模块的配网；
2. 配网功能来自于【汉枫】提供的功能，与 XAPP SDK 本身功能无任何关联，若配网中存在疑问请咨询【汉枫】的技术支持人员；
3. 建议自行开发 APP 时，重新集成配网功能，不要复用此 DEMO 中的配网功能；

2.2.2.2. 二维码订阅设备

需要二维码订阅设备时，请使用扫描二维码功能扫描设备二维码订阅。二维码订阅设备前，请务必确保设备已设置允许二维码订阅并且设备已上报二维码订阅相关的数据端点。

2.2.2.3. SN码订阅

SN 码订阅设备时需要提供设备的 SN 码，请确保设备允许二维码订阅并且设备存在 SN 码；设备至少需要已激活后才能进行订阅。

2.2.2.4. 第三方推送配置

第三方推送配置允许将应用与第三方推送关联，从而实现将消息推送转发到第三方推送，实现消息的离线推送与接收。

1. 目前支持的第三方推送配置支持：FCM 配置、阿里推送
2. 推送配置方式请参考开发指南相关文档

2.2.2.5. 辅助功能

1. 【修改产品ID】不属于 XAPP SDK 本身的功能，仅 DEMO 程序为了方便频繁切换产品ID提供的功能
2. 【日志信息】不属于 XAPP SDK 本身的功能，仅 DEMO 程序为了方便查看当前运行时保存的日志信息及管理日志文件夹下的日志文件列表提供的功能
3. 【推送消息记录】不属于 XAPP SDK 本身的功能，仅 DEMO 程序为了方便提供查看第三方推送消息的记录功能，所有消息仅缓存在内存中并且离线后不会记录消息
4. 【显示SDK版本】、【显示用户信息】均为方便显示当前 DEMO 使用的信息