文件传输

2026-11-05评分加载中…

一、功能介绍

插件 App 与 Pilot 运行在两个独立进程,插件无法直接把本地文件交给 Pilot 使用。文件传输能力把插件本地的文件推送到 Pilot 端并持久化保存,之后由 AR 投射、地图控件等能力以文件名引用这些资源。它是「先上传资源、再使用资源」这一模式的基础环节。

1.1 能力总览

能力描述
上传文件把插件本地文件推送到 Pilot 端保存,并回调上传进度
查询文件列表查询本插件已上传到 Pilot 端的文件名列表

1.2 应用场景

  • AR 投射:上传标注用到的 SVG 图标,供 AR 教程以文件名引用
  • 地图控件:上传 Marker 图标,供地图控件以文件名引用
  • 资源校验:上传前查询文件列表去重,或确认资源是否就绪

二、接口调用示例

以下示例假设你已完成 SDK 初始化,且插件与 Pilot 已连接就绪(连接状态获取见插件连接状态文档)。所有接口都通过管理器单例 FileTransferManager.getInstance() 调用。

2.1 上传文件(pushFileToRemote)

传入本地文件的绝对路径,回调分为进度、成功、失败三种。上传时只传本地路径,但 Pilot 端以文件名(不含目录)作为服务端唯一标识保存,后续能力都用这个文件名引用资源:

val fileManager = FileTransferManager.getInstance()             // 获取管理器单例

val filePath = "/sdcard/Android/data/<your_pkg>/files/star_max.svg"   // TODO: 替换为你的本地文件绝对路径

fileManager.pushFileToRemote(filePath, object : CommonCallbacks.CompletionCallbackWithProgress<Double> {
    override fun onProgressUpdate(progress: Double) {
        // 上传进度,取值 0.0 ~ 100.0(百分比)
    }
    override fun onSuccess() {
        // 上传完成;此后可用文件名 "star_max.svg" 引用该资源
    }
    override fun onFailure(error: IDJIError) {
        // error.errorCode() 获取错误码
    }
})

服务端的存储规则有三条:

  • 按插件包名隔离:每个插件的文件存放在各自独立目录下,互不可见。
  • 同名覆盖:上传与已有文件同名时,服务端先删旧文件再写新文件,因此同一文件名重复上传即为更新。
  • 进度只保证起止值:进度从 0.0 到 100.0;若无法获取文件大小则不上报中间进度,请以 onSuccess 作为完成判据。

注意:

  1. 上传是串行的,服务端同一时刻只处理一个上传任务。上一个上传未结束就发起新的,会立即回调 UPLOAD_FILE_BUSY。请等上一个上传的 onSuccess / onFailure 回调后再发起下一个,或在业务侧串行排队。
  2. 卸载插件后,该插件通过 pushFileToRemote 上传的文件会被删除。

2.2 查询已上传的文件列表(queryFileListFromRemote)

查询当前插件已上传到 Pilot 端的所有文件名,可用于上传前去重、或校验资源是否就绪:

fileManager.queryFileListFromRemote(object : CommonCallbacks.CompletionCallbackWithParam<List<String>> {
    override fun onSuccess(fileList: List<String>) {
        // fileList 为文件名列表,如 ["star_max.svg", "star_min.svg"]
        val alreadyUploaded = fileList.contains("star_max.svg")
    }
    override fun onFailure(error: IDJIError) {
        // error.errorCode() 获取错误码
    }
})

返回的仅为当前插件目录下的文件名;服务端目录不存在时返回空列表(而非失败)。


三、API 参考

以下接口方法的完整定义请查看 API 文档:IFileTransferManageropen in new window。

IFileTransferManager 是服务端文件传输管理接口总入口,对外开放以下方法:

项说明
IFileTransferManager文件传输管理接口总入口
pushFileToRemote上传本地文件到 Pilot 端,带进度回调
queryFileListFromRemote查询本插件已上传的文件名列表

四、Sample 源码获取

文件传输 Sampleopen in new window


五、常见问题(FAQ)

Q1:调用 pushFileToRemote 立即失败,回调 FILE_NOT_EXIST / EXECUTION_FAILED?

这些是上传前的本地校验失败,按下列顺序排查:

  1. FILE_NOT_EXIST:传入路径对应的文件不存在,检查绝对路径是否正确。
  2. EXECUTION_FAILED(非文件):传入的是目录而非文件,pushFileToRemote 一次只传单个文件。
  3. EXECUTION_FAILED(不可读):文件无读权限,确认应用具备存储权限、文件可读。

Q2:并发上传时回调 UPLOAD_FILE_BUSY?

服务端一次只处理一个上传任务。上一个上传未结束就发起新的,会立即返回 UPLOAD_FILE_BUSY。正确做法:在上一个上传的 onSuccess / onFailure 回调之后再发起下一个;批量上传时在业务侧串行排队,不要并发调用。

Q3:上传同名文件会重复保存还是覆盖?

覆盖。服务端以文件名为唯一标识,写入前先删除同名旧文件。因此「更新某个资源」的做法就是用相同文件名重新上传一次,无需先删除。

Q4:onProgressUpdate 没有中间进度,只跳到了 100?

服务端在无法获取文件大小时不上报中间百分比,只保证起始 0.0 与结束 100.0。这属于正常情况,请以 onSuccess 作为上传完成的判定依据,不要依赖中间进度值做业务逻辑。

Q5:pushFileToRemote 传路径,queryFileListFromRemote 却返回文件名,如何对应?

上传时传的是本地绝对路径,但服务端只取其中的文件名保存;查询返回的就是这些文件名。因此后续所有能力(如 AR 图标、Marker 图标)都用文件名引用资源,与本地路径无关。

附录:错误码速查

以下错误码来自 dji.open.pilot.base.error.RemoteError:

错误码常量触发场景处理建议
REMOTE_DISCONNECTED连接未就绪时调用等连接状态 CONNECTED 后重试
FILE_NOT_EXIST上传的本地文件不存在检查绝对路径;见 Q1
EXECUTION_FAILED路径非文件 / 不可读 / 传输异常确认是可读的单个文件;见 Q1
UPLOAD_FILE_BUSY已有上传任务进行中串行排队,待上一个上传结束再发起;见 Q2
最近修改: