A-XLinkConfig.Builder

一、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 接口文档了解

二、更新日志

日期 更新内容
2019-01-15 新增初始化配置参数,自v6.2.6.x版本起
2018-08-26 初稿,自 X-MQTT SDK v6.2版本起
没找到需要的文档?
你可以提交工单反馈 或 阅读常见问题