插件链接状态

2026-11-03评分加载中…

一、功能介绍

插件 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
最近修改: