统一互联开发指导—富对富文件互传

一、概述

统一互联是鸿蒙生态中实现设备间互联互通的核心技术体系，旨在打破平台壁垒、消除设备隔阂、贯通数据流与控制流，构建可互操作、可协同、可信任的全域数字网络。通过统一互联技术，能够打通OpenHarmony设备与消费类领域HarmonyOS Next标准设备的互联生态，实现跨厂商设备互联互通。

本指导文档聚焦于富对富文件互传场景，系统讲解从分享端(Source)开发到接收端(Sink)开发的核心技术路径，涵盖图库/文件管理器应用、文件互传应用、文件互传SDK组件以及分布式软总线等完整开发指南。当前支持OpenHarmony标准设备间的发现与文件互传。

二、技术架构总览

2.1 核心组成

组件	说明
图库应用(Photos)	媒体资源选择与分享入口，接收后预览展示
文件管理器应用(FileManager)	文件/文件夹选择与分享入口，接收后展示
文件互传应用(OH-Share)	文件互传主体业务UI交互，半模态服务
文件互传SDK(OH-Share-SDK)	文件分享核心系统服务，提供发现连接、会话管理、传输管理等能力
分布式设备管理(DeviceManager)	账号无关的分布式设备认证组网能力
分布式软总线(DSoftBus)	近场设备间统一的分布式通信管理能力

2.2 传输模式

模式	说明
Source端(分享端)	从本设备选择文件并向对端设备发起分享请求，负责文件发送
Sink端(接收端)	接收对端设备的分享请求，负责文件接收和存储
单次传输	文件互传为一次性认证，单次传输完成后自动断开连接
单任务模式	同一时刻只能处理一条分享任务，防止业务冲突

三、开发指南章节索引

3.1 基础概念与概述

章节	内容简介
使用说明	文件互传功能介绍、使用流程说明
框架设计	模块关系图、系统服务介绍

3.2 Source端开发

3.2.1 图库/文件管理器应用

图库/文件管理器应用是文件分享的入口，提供媒体资源/文件的选择与分享交互。

章节	内容简介
图库应用	Source端发起分享、Sink端接收后预览
文件管理器应用	Source端发起分享、Sink端接收后展示

3.2.2 文件互传应用Source端

文件互传应用负责文件互传主体业务的UI交互，向上对接图库/文件管理器，向下对接文件分享SDK。

章节	内容简介
文件互传应用概述	应用简介、公共代码流程、交互流程
文件互传应用Source端	接收分享请求、设备扫描、PIN码认证、文件发送

3.3 Sink端开发

3.3.1 文件互传应用Sink端

文件互传应用的Sink端与Source端共享一套代码，同一时刻只能作为其中之一。

章节	内容简介
文件互传应用Sink端	接收分享请求、PIN码认证、文件接收、拉起预览

3.3.2 设置/SystemUI应用

设置/SystemUI应用提供统一互联分享开关配置，控制Sink端是否可被发现。

章节	内容简介
系统设置应用	分享开关、分享时间设置
SystemUI应用	控制中心分享开关

3.4 SDK组件开发

3.4.1 文件互传SDK

文件互传SDK是文件分享的核心系统服务，提供发现连接、会话管理、传输管理、文件管理等能力。

章节	内容简介
file_share模块	client端与server端实现、文件发送接收流程

3.4.2 分布式设备管理

DeviceManager组件提供账号无关的分布式设备的认证组网能力，为文件互传提供设备发现、连接、鉴权功能。

章节	内容简介
device_manager模块	分享弹框重定向、PIN码认证扩展

3.4.3 分布式软总线

分布式软总线提供近场设备间统一的分布式通信管理能力，为文件互传提供数据传输通道。

章节	内容简介
dsoftbus模块	蓝牙广播UUID适配

3.5 接口设计

章节	内容简介
接口综述	接口历程图、接口文件获取
文件互传Source端接口	拉起Share应用接口、SDK接口
文件互传Sink端接口	拉起图库/文件管理器接口、SDK接口

3.6 问题定位指导

章节	内容简介
问题定位指导书	典型问题分析与解决步骤

四、开发流程指引

4.1 Source端开发流程

1. 图库/文件管理器集成

   • 获取图库/文件管理器应用源码
   • 参考接口设计文档，实现拉起文件互传应用功能
   • 配置分享参数(ShareWant)，包含分享类型、文件列表等信息

2. 开发文件互传应用Source端

   • 获取文件互传应用源码：applications_share
   • 实现SourceModel初始化：创建窗口、注册监听
   • 实现分享请求接收：解析ShareWant参数、开始设备扫描
   • 实现设备扫描：调用SDK的startScan接口
   • 实现设备连接：调用SDK的connect接口、处理PIN码认证
   • 实现文件发送：调用SDK的sendFile接口、监听传输进度

4.2 Sink端开发流程

1. 设置/SystemUI集成

   • 获取设置/SystemUI应用源码
   • 实现分享开关功能：调用SDK的enableShare/disableShare接口
   • 实现分享时间设置：调用SDK的setShareOpenTime接口
   • 监听分享状态变化：注册shareStatusChange监听

2. 开发文件互传应用Sink端

   • 实现SinkModel初始化：创建窗口、注册监听
   • 实现接收确认：处理确认弹框、调用confirmConnect接口
   • 实现PIN码认证监听：监听authStateChange事件
   • 实现文件接收：监听sendChange事件、处理传输进度
   • 实现接收后跳转：接收成功后拉起图库/文件管理器预览

4.3 SDK组件开发流程

1. 获取SDK源码

   • 文件互传SDK：distributeddatamgr_file_share
   • 设备管理：distributedhardware_device_manager
   • 分布式软总线：communication_dsoftbus

2. 理解SDK架构

   • Client端：提供napi接口供应用层调用，处理设备发现、连接、鉴权
   • Server端：系统服务(SA ID: 9555)，提供文件传输核心能力
   • IPC通信：Client与Server之间通过IPC通信

3. 关键定制点

   • 蓝牙广播UUID适配：扩展文件分享设备UUID(0xFE35)
   • 分享弹框重定向：将确认弹框重定向到文件互传应用
   • PIN码认证扩展：增加超时和重试机制，扩展事件上报类型

4.4 调试

1. 编译并烧录固件到两台富设备(RK3568或其他标准系统设备)
2. Sink端打开统一互联分享开关(设置或控制中心)
3. Source端从图库/文件管理器选择文件，点击分享
4. Source端扫描发现Sink端设备，选择设备进行分享
5. Sink端显示PIN码，Source端输入PIN码完成认证
6. 观察文件传输进度，验证传输成功
7. Sink端自动跳转图库/文件管理器显示接收文件

五、代码仓库索引

仓库名称	仓库地址	用途说明
文件互传应用	https://gitcode.com/ohos-oneconnect/applications_share	文件互传UI交互应用
图库应用	https://gitcode.com/ohos-oneconnect/applications_photos	媒体资源管理应用
文件管理器应用	https://gitcode.com/ohos-oneconnect/applications_filemanager	文件管理应用
设置应用	https://gitcode.com/ohos-oneconnect/applications_settings	系统设置应用
SystemUI应用	https://gitcode.com/ohos-oneconnect/applications_systemui	系统UI应用
文件互传SDK	https://gitcode.com/ohos-oneconnect/distributeddatamgr_file_share	文件分享核心服务
分布式设备管理	https://gitcode.com/ohos-oneconnect/distributedhardware_device_manager	设备发现连接鉴权
分布式软总线	https://gitcode.com/ohos-oneconnect/communication_dsoftbus	分布式通信基础能力