Open Harmony文件互传实现（整体框架分析）

文件互传整体框架┌─────────────────────────────────────────────────┐ │ 应用层 (Applications) │ │ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ Share 应用 │ │ OH-Share 应用 (图库分享) │ │ │ │ (Source/Sink) │ │ (照片/视频选择与分享) │ │ │ └──────┬───────┘ └──────────┬───────────────┘ │ │ │ ohos.oneConnect.fileShare API │ ├─────────┼──────────────────────┼────────────────┤ │ ▼ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ NAPI 层 (napi_file_share) │ │ │ │ JS ↔ C 桥接设备发现/认证/发送接口 │ │ │ └──────────────────┬───────────────────────┘ │ ├─────────────────────┼───────────────────────────┤ │ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ Inner API 层 (ShareManager/Client) │ │ │ │ IPC Client/Proxy/Callback 封装 │ │ │ └──────────────────┬───────────────────────┘ │ ├─────────────────────┼───────────────────────────┤ │ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ 服务层 (FileShareService/SA 9555) │ │ │ │ SendManager: 会话管理/文件发送/哈希校验 │ │ │ │ FileShareConfig: 存储/定时器配置 │ │ │ │ FileShareQueue: 异步任务队列 │ │ │ └──────────────────┬───────────────────────┘ │ ├─────────────────────┼───────────────────────────┤ │ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ 底层依赖: 分布式软总线 设备管理 文件权限 │ │ └──────────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘核心服务层 —foundation/distributeddatamgr/file_share/1. 公共定义模块 (common/)文件路径功能说明/home/liuyun/L0/foundation/distributeddatamgr/file_share/common/include/file_share_common.h定义文件互传核心数据结构SendTask、SendInfo、FileInfo、FSNapiFileInfo和枚举SendType、SendState、ShareType/home/liuyun/L0/foundation/distributeddatamgr/file_share/common/include/file_share_errors.h定义文件互传错误码通用错误、代理错误、分布式软总线错误等/home/liuyun/L0/foundation/distributeddatamgr/file_share/common/include/file_share_log.h文件互传日志工具定义/home/liuyun/L0/foundation/distributeddatamgr/file_share/common/include/jsonUtil.hppJSON 解析工具用于文件互传数据的序列化/反序列化/home/liuyun/L0/foundation/distributeddatamgr/file_share/common/event_monitor/event_monitor.cpp系统公共事件监听监听灭屏/锁屏事件自动关闭分享状态2. IPC 接口层 — Inner API (interfaces/inner_api/)文件路径功能说明/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/include/ipc/i_file_share_service.h文件互传服务 IPC 接口定义SendFile、CancelSendFile、SetShareStatus 等/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/include/ipc/i_file_share_callback.h文件互传回调接口定义OnSendEvent、OnShareStatusEvent及 SendFileCallback/ShareStatusCallback 抽象类/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/include/ipc/file_share_client.h文件互传客户端封装单例模式负责获取远端代理并发起 IPC 调用/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/include/ipc/file_share_proxy.h文件互传 IPC Proxy 端向服务端发送请求/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/include/ipc/file_share_callback.h文件互传回调实现类桥接 IPC 回调与本地 SendFileCallback/ShareStatusCallback/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/include/ipc/file_share_callback_stub.h文件互传回调 Stub 端处理服务端到客户端的回调 IPC 请求/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/include/share_manager.h文件互传管理器单例提供 SendFile、RegisterCallback、CancelSendFile、SetShareStatus 等能力/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/src/ipc/file_share_client.cppFileShareClient 实现管理代理获取与死亡监听/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/src/ipc/file_share_proxy.cppFileShareProxy 实现IPC 请求序列化与发送/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/src/ipc/file_share_callback.cppFileShareCallback 实现分发 IPC 回调到本地回调对象/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/src/ipc/file_share_callback_stub.cppFileShareCallbackStub 实现处理 OnSendEvent/OnShareStatusEvent 的 IPC 反序列化/home/liuyun/L0/foundation/distributeddatamgr/file_share/interfaces/inner_api/src/share_manager.cppShareManager 实现整合 Client 与 Callback 的业务逻辑3. 服务端实现 (services/)文件路径功能说明/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/include/ipc/file_share_service.h文件互传系统服务SystemAbility继承 FileShareStub管理服务生命周期/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/include/ipc/file_share_stub.h文件互传 IPC Stub 端分发客户端请求到对应处理函数/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/include/ipc/file_share_callback_proxy.h文件互传回调 Proxy 端向客户端发送事件通知/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/include/share/send_manager.h文件发送管理器单例核心业务逻辑创建会话、发送文件、管理会话信息、通知事件/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/include/share/file_share_queue.h文件互传线程安全队列模板用于异步任务调度/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/include/share/file_share_config.h文件互传配置管理存储路径、工作时长、倒计时定时器/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/include/utils/file_hash.h文件哈希工具MD5/SHA1/SHA256用于文件完整性校验/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/src/ipc/file_share_service.cppFileShareService 实现OnStart/OnStop 生命周期及业务方法/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/src/ipc/file_share_stub.cppFileShareStub 实现OnRemoteRequest 请求分发/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/src/ipc/file_share_callback_proxy.cppFileShareCallbackProxy 实现发送回调事件到客户端/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/src/share/send_manager.cppSendManager 实现核心创建分布式会话、发送文件、处理接收、校验哈希、通知进度/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/src/share/file_share_queue.cppFileShareQueue 模板实现/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/src/share/file_share_config.cppFileShareConfig 实现偏好设置存储、倒计时定时器/home/liuyun/L0/foundation/distributeddatamgr/file_share/services/src/utils/file_hash.cppFileHash 实现MD5/SHA1/SHA256 文件哈希计算4. SA 配置 (sa_profile/)文件路径功能说明/home/liuyun/L0/foundation/distributeddatamgr/file_share/sa_profile/9555.json系统能力 SA 配置SA ID 9555/home/liuyun/L0/foundation/distributeddatamgr/file_share/sa_profile/file_share_service.cfg文件互传服务进程配置5. NAPI/JS 接口层 (frameworks/js/)文件路径功能说明/home/liuyun/L0/foundation/distributeddatamgr/file_share/frameworks/js/include/napi_file_share.hNAPI 文件互传模块定义封装设备发现、认证、发送等 JS 接口/home/liuyun/L0/foundation/distributeddatamgr/file_share/frameworks/js/include/napi_file_share_event.hNAPI 事件机制封装On/Off/OnEvent支持 JS 层事件监听/home/liuyun/L0/foundation/distributeddatamgr/file_share/frameworks/js/include/napi_file_share_util.hNAPI 工具函数JS 对象与 C 结构体转换、错误码定义/home/liuyun/L0/foundation/distributeddatamgr/file_share/frameworks/js/include/napi_init.hNAPI 模块注册入口/home/liuyun/L0/foundation/distributeddatamgr/file_share/frameworks/js/src/napi_file_share.cppNAPI 文件互传核心实现暴露 ShareManager JS API/home/liuyun/L0/foundation/distributeddatamgr/file_share/frameworks/js/src/napi_file_share_event.cppNAPI 事件机制实现/home/liuyun/L0/foundation/distributeddatamgr/file_share/frameworks/js/src/napi_file_share_util.cppNAPI 工具函数实现/home/liuyun/L0/foundation/distributeddatamgr/file_share/frameworks/js/src/napi_init.cppNAPI 模块初始化注册应用层 — Share 应用applications/standard/share/1. 产品层 — Phone (product/phone/)文件路径功能说明/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/models/ohos.oneConnect.fileShare.d.ts文件互传 JS API 类型声明ShareWant、SharedRecord、ShareType、SendState 等/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/models/SourceModel.ets发送端Source业务模型设备发现、连接、文件发送/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/models/SinkModel.ets接收端Sink业务模型接收文件、保存到相册/文件管理器/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/models/ConfirmDialogModel.ts确认对话框数据模型/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/pages/ShareSourceDialogPage.ets发送端对话框页面 UI/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/pages/ShareSinkDialogPage.ets接收端对话框页面 UI/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/pages/ConfirmDialog.ets确认对话框页面/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/serviceextability/ServiceExtAbility.ets文件互传 ServiceExtensionAbility后台服务入口/home/liuyun/L0/applications/standard/share/product/phone/src/main/ets/confirmuiextability/ConfirmUIExtAbility.ets确认 UI ExtensionAbility2. 功能模块 — Share Feature (features/share/)文件路径功能说明/home/liuyun/L0/applications/standard/share/features/share/src/main/ets/manager/ShareManager.tsShare 管理器封装 oneConnectShare API管理设备发现/连接/发送回调/home/liuyun/L0/applications/standard/share/features/share/src/main/ets/constants/Constants.ts常量定义/home/liuyun/L0/applications/standard/share/features/share/src/main/ets/constants/DeviceInfo.ets设备信息数据类/home/liuyun/L0/applications/standard/share/features/share/src/main/ets/constants/FileInfo.ets文件信息数据类/home/liuyun/L0/applications/standard/share/features/share/src/main/ets/components/DeviceIcon.ets设备图标组件/home/liuyun/L0/applications/standard/share/features/share/src/main/ets/components/PreviewGallery.ets文件预览画廊组件3. 公共模块 — Common (common/)文件路径功能说明/home/liuyun/L0/applications/standard/share/common/src/main/ets/default/utils/FileUtil.ts文件操作工具类/home/liuyun/L0/applications/standard/share/common/src/main/ets/default/manager/NotificationManager.ts通知管理器发送文件互传通知/home/liuyun/L0/applications/standard/share/common/src/main/ets/default/manager/WindowManager.ts窗口管理器管理互传弹窗/home/liuyun/L0/applications/standard/share/common/src/main/ets/default/manager/ResourceManager.ts资源管理器/home/liuyun/L0/applications/standard/share/common/src/main/ets/default/manager/PreferenceManager.ts偏好设置管理器/home/liuyun/L0/applications/standard/share/common/src/main/ets/default/manager/DelayTaskManager.ts延迟任务管理器应用层 — OH-Share 应用applications/standard/oh-share/该应用是图库分享场景的专用互传应用基于相册浏览器架构支持照片/视频的选择与分享。文件路径功能说明/home/liuyun/L0/applications/standard/oh-share/common/src/main/ets/default/model/common/FileSendModel.ts文件发送数据模型/home/liuyun/L0/applications/standard/oh-share/common/src/main/ets/default/model/common/WifiManager.tsWiFi 管理器/home/liuyun/L0/applications/standard/oh-share/common/src/main/ets/default/view/browserOperation/ShareMenuOperation.ts分享菜单操作逻辑/home/liuyun/L0/applications/standard/oh-share/common/src/main/ets/default/view/dialog/ShareDialog.ets分享对话框 UI/home/liuyun/L0/applications/standard/oh-share/common/src/main/ets/default/view/dialog/ReceivedDialog.ets接收对话框 UI/home/liuyun/L0/applications/standard/oh-share/common/src/main/ets/default/view/dialog/SaveDialog.ets保存对话框 UI/home/liuyun/L0/applications/standard/oh-share/common/src/main/ets/default/view/dialog/ProgressDialog.ets传输进度对话框 UI/home/liuyun/L0/applications/standard/oh-share/common/src/main/ets/default/access/UserFileManagerAccess.ts用户文件管理器访问接口文件权限/URI 共享层 —foundation/filemanagement/app_file_service/该模块提供跨应用文件 URI 权限共享能力是文件互传的底层权限支撑。文件路径功能说明/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/innerkits/native/file_share/include/file_share.h文件共享接口CreateShareFile/DeleteShareFile管理 URI 粒度的文件共享/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/innerkits/native/file_share/src/file_share.cppFileShare 实现/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/innerkits/native/file_share/include/file_permission.h文件权限策略定义UriPolicyInfo、OperationMode、PolicyFlag 等/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/innerkits/native/file_share/src/file_permission.cppFilePermission 实现管理持久化/临时文件权限策略/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/kits/js/file_share/fileshare_n_exporter.hJS 层文件共享 NAPI 导出声明/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/kits/js/file_share/fileshare_n_exporter.cppJS 层文件共享 NAPI 导出实现/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/kits/js/file_share/grant_uri_permission.hURI 权限授予 NAPI 声明/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/kits/js/file_share/grant_uri_permission.cppURI 权限授予 NAPI 实现/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/kits/js/file_share/grant_permissions.h批量权限授予 NAPI 声明/home/liuyun/L0/foundation/filemanagement/app_file_service/interfaces/kits/js/file_share/grant_permissions.cpp批量权限授予 NAPI 实现适配层定位结构图示文件互传的适配层在整体框架中处于核心服务层与外部系统能力之间的桥梁位置相当于南向开发的门面从这些接口可以管中窥豹熟悉整个项目共6 个适配层应用层 ↕ NAPI适配层 (JS ↔ C) 服务客户端 ↕ IPC适配层 (跨进程通信) 服务端核心 ↕ 分布式软总线适配层 (传输通道) ↕ 设备管理适配层 (设备发现/认证) ↕ 文件权限适配层 (URI权限/沙箱) ↕ 媒体库适配层 (媒体资产保存) 底层系统能力文件互传整体框架与适配层位置┌─────────────────────────────────────────────────────────────────────┐ │ 应用层 (Applications) │ │ Share 应用 (Source/Sink) OH-Share 应用 (图库分享) │ │ │ │ │ │ ohos.oneConnect.fileShare API ohos.oneConnect.fileShare │ └─────────┼──────────────────────────────────┼───────────────────────┘ │ │ ══════════╪══════════════════════════════════╪═══════════════════════ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ ★ 适配层1: NAPI 适配层 (frameworks/js/) │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ napi_file_share.cpp JS ↔ C 类型转换、回调桥接 │ │ │ │ napi_file_share_event 事件机制适配 (uv_queue_work) │ │ │ │ napi_file_share_util JS对象 ↔ C结构体 序列化/反序列化 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ 作用: 将 C 原生能力适配为 JS/ArkTS 可调用的 API │ ═══════════════════════════════════════════════════════════════════════ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ ★ 适配层2: IPC 适配层 (interfaces/inner_api/) │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 客户端侧: │ │ │ │ FileShareClient → 获取远端 SA 代理 │ │ │ │ FileShareProxy → IPC 请求序列化与发送 │ │ │ │ FileShareCallbackStub → IPC 回调反序列化 │ │ │ │ 服务端侧: │ │ │ │ FileShareStub → IPC 请求反序列化与分发 │ │ │ │ FileShareCallbackProxy → IPC 回调序列化与发送 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ 作用: 适配跨进程通信使客户端进程可调用服务端 SA(9555) 的能力 │ ═══════════════════════════════════════════════════════════════════════ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ 服务层 (services/) │ │ ┌──────────────┐ ┌───────────────┐ ┌──────────────────────┐ │ │ │FileShareService│ │ SendManager │ │ FileShareConfig │ │ │ │ (SA 9555) │ │ (发送管理器) │ │ (配置/定时器) │ │ │ └──────────────┘ └───────┬───────┘ └──────────────────────┘ │ └────────────────────────────┼───────────────────────────────────────┘ │ ════════════════════════════╪═════════════════════════════════════════ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ ★ 适配层3: 分布式软总线适配层 (send_manager.cpp 内部) │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ ISessionListener → 会话开/关/消息回调适配 │ │ │ │ IFileSendListener → 发送进度/完成/错误回调适配 │ │ │ │ IFileReceiveListener → 接收进度/完成/重命名回调适配 │ │ │ │ │ │ │ │ 适配调用: │ │ │ │ CreateSessionServer() → 注册会话服务 │ │ │ │ OpenSession() → 建立传输通道 │ │ │ │ SendFile() → 发送文件 │ │ │ │ GetPeerDeviceId() → 获取对端设备ID │ │ │ │ CloseSession() → 关闭会话 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ 作用: 适配分布式软总线传输能力将文件互传业务映射为会话文件传输 │ ═══════════════════════════════════════════════════════════════════════ │ │ │ ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ ★ 适配层4: │ │ ★ 适配层5: │ │ ★ 适配层6: │ │ 设备管理适配 │ │ 文件权限适配 │ │ 媒体库适配 │ │ │ │ │ │ │ │ DeviceManager │ │ FileShare │ │ UserFileClient │ │ ·设备发现 │ │ ·CreateShareFile │ │ ·HandleMediaAsset │ │ ·设备认证 │ │ ·DeleteShareFile │ │ ·CopyFileToMediaAsset│ │ ·设备上下线 │ │ ·FilePermission │ │ ·媒体相册分享 │ │ ·PIN码认证 │ │ ·URI权限授予 │ │ ·MimeTypeUtils │ │ ·发布/订阅 │ │ ·grantUriPerm │ │ ·MediaFileUtils │ └──────────────────┘ └──────────────────┘ └──────────────────────┘ │ 作用: 适配设备发现 │ 作用: 适配跨应用 │ 作用: 适配接收文件 │ │ 与认证能力 │ 文件URI权限共享 │ 保存到媒体库 │ ═══════════════════════════════════════════════════════════════════════ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ OpenHarmony 底层系统能力 │ │ 分布式软总线(dsoftbus) 设备管理服务 文件管理服务 媒体库 │ └─────────────────────────────────────────────────────────────────────┘六大适配层详解适配层1: NAPI 适配层项目说明位置foundation/distributeddatamgr/file_share/frameworks/js/方向JS/ArkTS ↔ C Native核心文件napi_file_share.cpp, napi_file_share_event.h, napi_file_share_util.h适配内容JS 对象 ↔ C 结构体转换JsToDmPublishInfo等、C 回调 → JS 事件uv_queue_work跨线程回调、NAPI 函数注册导出适配层2: IPC 适配层项目说明位置foundation/distributeddatamgr/file_share/interfaces/inner_api/services/include/ipc/方向客户端进程 ↔ 服务端进程 (SA 9555)核心文件file_share_proxy.h, file_share_client.h, file_share_stub.h, file_share_callback_proxy.h适配内容Proxy 端序列化请求 → Stub 端反序列化分发、服务端回调 → 客户端 CallbackStub 通知、SA 代理获取与死亡监听适配层3: 分布式软总线适配层项目说明位置foundation/distributeddatamgr/file_share/services/src/share/send_manager.cpp内部方向文件互传服务 ↔ 分布式软总线 (dsoftbus)核心代码ISessionListener、IFileSendListener、IFileReceiveListener三个回调结构体适配内容将文件互传业务映射为软总线会话模型CreateSessionServer→OpenSession→SendFile/接收 →CloseSession会话开/关/消息回调 → SendManager 事件通知文件传输进度/完成/错误回调 → 进度计算与状态更新适配层4: 设备管理适配层项目说明位置napi_file_share.cpp中 DeviceManager 调用 send_manager.cpp中设备管理方向文件互传 ↔ 设备管理服务 (DeviceManager)适配内容设备发现StartDeviceDiscovery、设备发布PublishDeviceDiscovery、设备认证AuthenticateDevice/PIN码、设备状态回调OnDeviceOnline/Offline/Ready、网络ID ↔ 设备ID 转换适配层5: 文件权限适配层项目说明位置foundation/filemanagement/app_file_service/interfaces/innerkits/native/file_share/方向文件互传 ↔ 文件权限/沙箱管理核心文件file_share.h, file_permission.h适配内容URI 粒度的文件共享权限CreateShareFile/DeleteShareFile、跨应用 URI 权限授予grantUriPermission、沙箱路径 ↔ 物理路径转换SandboxHelper::GetPhysicalPath适配层6: 媒体库适配层项目说明位置send_manager.cpp中HandleMediaAsset/CopyFileToMediaAsset方向文件互传 ↔ 媒体库 (UserFileClient/MediaLibrary)适配内容接收文件保存到媒体相册分享相册、UserFileClient媒体文件操作、MediaFileUtils/MimeTypeUtils文件类型识别与处理