文件传输
一、功能介绍
插件 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作为完成判据。
注意:
- 上传是串行的,服务端同一时刻只处理一个上传任务。上一个上传未结束就发起新的,会立即回调
UPLOAD_FILE_BUSY。请等上一个上传的onSuccess/onFailure回调后再发起下一个,或在业务侧串行排队。- 卸载插件后,该插件通过
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 文档:IFileTransferManager。
IFileTransferManager 是服务端文件传输管理接口总入口,对外开放以下方法:
| 项 | 说明 |
|---|---|
IFileTransferManager | 文件传输管理接口总入口 |
pushFileToRemote | 上传本地文件到 Pilot 端,带进度回调 |
queryFileListFromRemote | 查询本插件已上传的文件名列表 |
四、Sample 源码获取
五、常见问题(FAQ)
Q1:调用 pushFileToRemote 立即失败,回调 FILE_NOT_EXIST / EXECUTION_FAILED?
这些是上传前的本地校验失败,按下列顺序排查:
FILE_NOT_EXIST:传入路径对应的文件不存在,检查绝对路径是否正确。EXECUTION_FAILED(非文件):传入的是目录而非文件,pushFileToRemote一次只传单个文件。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 |