插件链接状态
一、功能介绍
插件 App 与 Pilot 运行在两个独立进程中,Pilot 开放的所有能力(AR 投射、地图控件、文件传输、自定义组件等)都依赖两者之间的一条跨进程连接。连接状态获取能力让插件实时感知这条链路的通断:连接就绪后再发起业务调用,断开后及时停止操作并提示用户,版本不兼容时给出明确引导。它是使用其他一切开放能力的前置环节。
1.1 能力总览
| 能力 | 描述 |
|---|---|
| 连接状态监听 | 注册监听器,实时接收插件与 Pilot 的连接状态变化 |
| 版本兼容错误通知 | 插件与 Pilot 版本不兼容时,通过监听器接收错误回调 |
| 监听移除 | 页面销毁时移除监听器,避免回调持有页面引用 |
1.2 应用场景
- 插件首页:展示「已连接 / 未连接」状态徽标
- 业务初始化:连接成功后再上传 AR 配置、绘制自定义组件
- 异常兜底:连接断开时暂停数据上报,引导用户检查 Pilot
二、接口调用示例
以下示例假设你已完成 SDK 初始化(链接模式 REMOTE_PILOT),插件已被 Pilot 拉起。所有接口都通过管理器单例 RemoteLinkManager.getInstance() 调用。
2.1 监听连接状态(addServerStateListener)
注册一个 IServerStateListener,即可接收状态变化与版本兼容错误两类回调。连接由 SDK 初始化流程自动驱动,插件无需手动发起:
val linkManager = RemoteLinkManager.getInstance() // 获取管理器单例
private val serverStateListener = object : IServerStateListener {
override fun onStateChanged(status: ServerState) {
when (status) {
ServerState.CONNECTED -> { /* 连接就绪:可调用其他开放能力 */ }
ServerState.DISCONNECT -> { /* 连接断开:停止业务调用,提示用户 */ }
ServerState.INCOMPATIBLE -> { /* 版本不兼容:引导对齐版本 */ }
ServerState.UNINITIALIZED -> { /* 服务未初始化 */ }
}
}
override fun onVersionCompatibleError(error: IDJIError) {
// 版本不兼容详情,通过 error.errorCode() 获取错误码
}
}
linkManager.addServerStateListener(serverStateListener) // 同一监听重复添加会自动去重
ServerState 有四个取值,是插件做连接决策的依据:
| 枚举 | 含义 | 典型触发 |
|---|---|---|
UNINITIALIZED | 服务未初始化 | SDK 尚未初始化 |
CONNECTED | 已连接 | 各 Manager 的 delegate 已注入,可用 |
DISCONNECT | 已断开 | Pilot 退出 / 进程死亡(单例初始状态也是它) |
INCOMPATIBLE | 版本不兼容 | 插件与 Pilot 版本不匹配 |
说明: 注册成功后会立即用当前缓存状态回调一次(初始为
DISCONNECT),因此无需额外的「查询当前状态」接口。相同状态不会重复通知,只有真实切换才回调。
注意: 状态回调的触发线程取决于事件来源(如 Binder 死亡通知运行在 Binder 线程),更新 UI 前请先切换到主线程。
效果预览:


2.2 连接成功后再初始化业务(CONNECTED 门控)
其他开放能力(ARManager、MapWidgetManager、FileTransferManager 等)的 delegate 在连接建立后才注入,因此业务初始化应收敛到 CONNECTED 分支:
override fun onStateChanged(status: ServerState) {
if (status == ServerState.CONNECTED) {
// 此刻起各 Manager 的 delegate 已注入,可安全调用,例如:
// 1. 上传插件用到的 SVG / 图片资源到 Pilot
// 2. 绘制自定义组件、注册各业务 Manager 的监听器
}
}
2.3 移除监听(removeServerStateListener)
页面(Activity / Fragment)销毁时移除监听器:
override fun onDestroy() {
super.onDestroy()
linkManager.removeServerStateListener(serverStateListener)
}
注意: 监听器列表由全局单例长期持有(
CopyOnWriteArrayList)。不移除会让匿名内部类隐式持有外部 Activity,造成内存泄漏,页面重建后还会多挂一份监听。请在onDestroy中成对移除。
三、接口概览
IRemoteLinkManager 是插件连接状态管理接口总入口,对外开放以下方法:
| 项 | 说明 |
|---|---|
IRemoteLinkManager | 插件连接状态管理接口总入口 |
addServerStateListener | 添加连接状态监听 |
removeServerStateListener | 移除连接状态监听 |
init | 初始化(当前为空实现,连接由 SDK 初始化流程自动驱动,无需手动调用) |
destroy | 销毁(当前为空实现) |
四、常见问题(FAQ)
Q1:为什么注册监听后会立即收到一次回调,而且是 DISCONNECT?
addServerStateListener 添加成功后会立即把当前缓存状态回调给新监听器,而单例的初始状态是 DISCONNECT。这保证任意时刻注册都能立刻拿到最新状态,无需额外查询接口。因此不要假设「第一次回调就是状态变化」,按状态值正常分支处理即可。
Q2:在 CONNECTED 之前调用其他开放能力(如 AR 投射)会怎样?
其他 Manager 的 delegate 只有连接建立后才注入。连接未就绪时调用会立刻失败并回调 REMOTE_DISCONNECTED(error.errorCode() 可获取)。推荐把所有业务调用收敛到 CONNECTED 分支之后(见 2.2),或对每个回调处理 REMOTE_DISCONNECTED 重试。
Q3:状态没有变化时会收到重复回调吗?
不会。SDK 内部更新状态时会先与当前值比较,相同则直接丢弃。只有真实切换(如 DISCONNECT → CONNECTED)才触发回调。
Q4:收到 INCOMPATIBLE 状态或 onVersionCompatibleError 回调怎么办?
表示插件与 Pilot 版本不匹配,连接不可用。通过 error.errorCode() 确认具体类型,将插件与 Pilot 对齐到相互兼容的版本后重新连接。
Q5:init / destroy 需要手动调用吗?
不需要。二者当前为空实现(预留)。连接的建立与断开由 SDK 初始化流程自动驱动,插件只需注册 / 移除监听即可。
附录:错误码速查
以下错误码来自 dji.open.pilot.base.error.RemoteError:
| 错误码常量 | 触发场景 | 处理建议 |
|---|---|---|
REMOTE_DISCONNECTED | 连接未就绪时调用其他开放能力 | 等 CONNECTED 后重试;见 Q2 |