当前位置： 首页 > news >正文

【OpenHarmony】用户文件服务模块架构

news 2025/9/29 6:09:19

用户文件服务模块架构

1. 模块概述

公共文件访问框架(FileAccessFramework)提供了一套公共文件访问和管理的接口。公共文件访问框架中FileAccessFramework向下对接底层文件管理服务，如medialibrary、externalFileManager。FileAccessFramework向上对接应用，提供对公共文件操作的基础能力。

源码：https://gitee.com/openharmony/filemanagement_user_file_service

1.1 功能与目标

主要功能：
用户文件服务模块（User File Service）是OpenHarmony系统中的公共文件访问框架（FileAccessFramework），提供了一套统一的文件访问和管理接口。该模块的主要功能包括：

  • 文件操作管理：提供查询、创建、删除、打开、移动、重命名用户公共文件路径下媒体文件和文档文件的能力
  • 多设备文件访问：支持访问共享盘设备、外置存储设备上的文件，以目录树方式呈现
  • 媒体文件管理：支持图片、音频、视频等媒体文件的相册方式呈现和管理
  • 文件选择器：提供文件选择器功能，支持应用选择文件
  • 文件观察者：提供文件变化监听和通知机制
  • 权限管理：集成文件访问权限控制和验证

使用场景：

  • 文件管理器应用的文件操作
  • 文件选择器组件的文件选择
  • 媒体应用的文件访问
  • 跨设备文件共享和管理
  • 第三方应用的文件操作需求

1.2 系统位置

系统架构位置：
用户文件服务模块位于OpenHarmony系统的foundation/filemanagement子系统下，是文件管理框架的核心组件之一。

模块关系：

  • 上层对接：为应用层提供文件访问API，支持JS、Native、C等多种接口形式
  • 下层对接：对接底层文件管理服务，如medialibrary、externalFileManager等
  • 横向协作：与app_file_service、storage_service等模块协作
  • 系统集成：集成到系统能力管理器中，提供系统级文件访问能力

核心模块地位：
该模块是文件管理子系统的核心模块，承担着统一文件访问接口的重要职责，是连接应用和底层存储服务的关键桥梁。

1.3 设计思路与模式

设计思路：

  • 统一接口设计：通过FileAccessFramework提供统一的文件访问接口，屏蔽底层存储差异
  • 扩展性架构：采用Extension机制，支持不同存储提供者的插件化接入
  • 异步处理机制：采用异步回调模式，提高系统响应性能
  • 权限安全控制：集成权限验证机制，确保文件访问安全
  • 多语言支持：提供JS、Native、C等多种语言接口

设计模式：

  • 代理模式：FileAccessService作为代理，管理Extension连接和请求转发
  • 观察者模式：文件变化通知机制，支持多观察者订阅
  • 工厂模式：Extension创建和管理机制
  • 单例模式：FileAccessService采用单例模式确保全局唯一性
  • 策略模式：不同存储类型的处理策略

1.4 系统框图

系统服务
底层服务
接口层
用户文件服务模块
应用层
权限管理
系统能力管理
进程间通信
MediaLibrary
ExternalFileManager
StorageService
AppFileService
JS API
Native API
C API
Picker API
FileAccessService
FileAccessExtAbility
Extension管理
观察者管理
权限验证
文件管理器
文件选择器
媒体应用
第三方应用

2. 模块结构

2.1 源文件与头文件

核心服务文件：

  • services/native/file_access_service/include/file_access_service.h - 文件访问服务主类定义
  • services/native/file_access_service/src/file_access_service.cpp - 文件访问服务实现
  • services/native/file_access_service/include/file_access_service_client.h - 服务客户端接口
  • services/native/file_access_service/src/file_access_service_client.cpp - 服务客户端实现

Extension相关文件：

  • interfaces/inner_api/file_access/include/file_access_ext_ability.h - Extension能力基类
  • interfaces/inner_api/file_access/src/file_access_ext_ability.cpp - Extension能力实现
  • interfaces/inner_api/file_access/include/file_access_extension_info.h - Extension信息定义
  • interfaces/inner_api/file_access/include/app_file_access_ext_connection.h - Extension连接管理

接口定义文件：

  • interfaces/inner_api/file_access/IFileAccessExtBase.idl - Extension基础接口定义
  • services/IFileAccessServiceBase.idl - 服务基础接口定义
  • services/IFileAccessObserver.idl - 观察者接口定义
  • services/NotifyType.idl - 通知类型定义

JS API文件：

  • frameworks/js/napi/file_access_module/napi_fileaccess_helper.h - JS文件访问助手
  • frameworks/js/napi/file_access_module/native_fileaccess_module.cpp - Native模块实现
  • frameworks/js/napi/file_access_ext_ability/file_access_ext_ability_module.cpp - Extension模块

Picker相关文件：

  • interfaces/kits/picker/include/picker_n_exporter.h - Picker导出器
  • interfaces/kits/picker/src/picker_n_exporter.cpp - Picker实现
  • interfaces/kits/picker/picker.js - JS接口定义

工具和辅助文件：

  • utils/file_access_check_util.h - 文件访问检查工具
  • utils/file_access_framework_errno.h - 错误码定义
  • utils/file_util.h - 文件工具函数

2.2 类、结构体、函数与方法

核心类定义：

FileAccessService类
class FileAccessService final : public SystemAbility, public FileAccessServiceBaseStub {
public:// 服务管理static sptr<FileAccessService> GetInstance();void Init();virtual void OnStart() override;virtual void OnStop() override;// 观察者管理int32_t RegisterNotify(const Uri &uri, bool notifyForDescendants, const sptr<IFileAccessObserver> &observer,const ConnectExtensionInfo& info);int32_t UnregisterNotify(const Uri &uri, const sptr<IFileAccessObserver> &observer,const ConnectExtensionInfo& info);// Extension管理int32_t GetExtensionProxy(const ConnectExtensionInfo& info,sptr<IFileAccessExtBase> &extensionProxy);int32_t ConnectFileExtAbility(const AAFwk::Want &want,const sptr<AAFwk::IAbilityConnection>& connection);private:// 内部管理std::unordered_map<std::string, std::shared_ptr<ObserverNode>> relationshipMap_;HolderManager<std::shared_ptr<ObserverContext>> obsManager_;std::unordered_map<std::string, sptr<IFileAccessExtBase>> cMap_;
};
FileAccessExtAbility类
class FileAccessExtAbility : public ExtensionBase<> {
public:// 文件操作接口virtual int OpenFile(const Uri &uri, const int flags, int &fd);virtual int CreateFile(const Uri &parent, const std::string &displayName, Uri &newFile);virtual int Mkdir(const Uri &parent, const std::string &displayName, Uri &newFile);virtual int Delete(const Uri &sourceFile);virtual int Move(const Uri &sourceFile, const Uri &targetParent, Uri &newFile);virtual int Copy(const Uri &sourceUri, const Uri &destUri, std::vector<Result> &copyResult, bool force = false);virtual int Rename(const Uri &sourceFile, const std::string &displayName, Uri &newFile);// 文件查询接口virtual int ListFile(const FileInfo &fileInfo, const int64_t offset, const int64_t maxCount,const FileFilter &filter, std::vector<FileInfo> &fileInfoVec);virtual int ScanFile(const FileInfo &fileInfo, const int64_t offset, const int64_t maxCount,const FileFilter &filter, std::vector<FileInfo> &fileInfoVec);virtual int Query(const Uri &uri, std::vector<std::string> &columns, std::vector<std::string> &results);// 文件信息接口virtual int GetFileInfoFromUri(const Uri &selectFile, FileInfo &fileInfo);virtual int GetFileInfoFromRelativePath(const std::string &selectFile, FileInfo &fileInfo);virtual int GetRoots(std::vector<RootInfo> &rootInfoVec);virtual int Access(const Uri &uri, bool &isExist);// 观察者接口virtual int StartWatcher(const Uri &uri);virtual int StopWatcher(const Uri &uri);
};

重要结构体：

FileInfo结构体
struct FileInfo : public virtual OHOS::Parcelable {
public:std::string uri { "" };           // 文件URIstd::string relativePath { "" };  // 相对路径std::string fileName { "" };      // 文件名int32_t mode { 0 };              // 文件模式int64_t size { 0 };              // 文件大小int64_t mtime { 0 };             // 修改时间std::string mimeType { "" };      // MIME类型// 序列化支持bool ReadFromParcel(Parcel &parcel);virtual bool Marshalling(Parcel &parcel) const override;static FileInfo *Unmarshalling(Parcel &parcel);
};
RootInfo结构体
struct RootInfo : public virtual OHOS::Parcelable {
public:int32_t deviceType { 0 };        // 设备类型std::string uri { "" };          // 根URIstd::string relativePath { "" }; // 相对路径std::string displayName { "" };   // 显示名称int32_t deviceFlags { 0 };       // 设备标志// 序列化支持bool ReadFromParcel(Parcel &parcel);virtual bool Marshalling(Parcel &parcel) const override;static RootInfo *Unmarshalling(Parcel &parcel);
};
Result结构体
struct Result : public virtual OHOS::Parcelable {
public:std::string sourceUri { "" };    // 源URIstd::string destUri { "" };       // 目标URIint32_t errCode { 0 };           // 错误码std::string errMsg { "" };        // 错误消息// 序列化支持bool ReadFromParcel(Parcel &parcel);virtual bool Marshalling(Parcel &parcel) const override;static Result *Unmarshalling(Parcel &parcel);
};

2.3 继承与多态

继承关系：

  • FileAccessService 继承自 SystemAbility 和 FileAccessServiceBaseStub，实现系统服务能力
  • FileAccessExtAbility 继承自 ExtensionBase<>，提供Extension能力基类
  • FileInfo、RootInfo、Result 等结构体继承自 Parcelable，支持跨进程序列化
  • ObserverContext 和 ObserverNode 提供观察者模式的基础实现

多态设计：

  • Extension机制支持不同存储提供者的插件化实现
  • 观察者模式支持多种文件变化事件的统一处理
  • 接口抽象实现不同文件操作类型的统一管理
  • 回调机制支持异步操作结果的统一处理

2.4 类图

manages
manages
creates
uses
«abstract»
SystemAbility
+OnStart()
+OnStop()
+Init()
«interface»
FileAccessServiceBaseStub
+RegisterNotify()
+UnregisterNotify()
+GetExtensionProxy()
+ConnectFileExtAbility()
FileAccessService
-instance_: sptr<FileAccessService>
-relationshipMap_: unordered_map
-obsManager_: HolderManager
-cMap_: unordered_map
+GetInstance() : sptr<FileAccessService>
+OnStart()
+OnStop()
+RegisterNotify()
+UnregisterNotify()
+GetExtensionProxy()
+ConnectFileExtAbility()
«abstract»
ExtensionBase
+Init()
FileAccessExtAbility
-creator_: CreatorFunc
+Create()
+OpenFile()
+CreateFile()
+Delete()
+Move()
+Copy()
+ListFile()
+GetRoots()
+StartWatcher()
+StopWatcher()
«interface»
IFileAccessExtBase
+OpenFile()
+CreateFile()
+Delete()
+Move()
+Copy()
+ListFile()
+GetRoots()
«interface»
Parcelable
+Marshalling()
+ReadFromParcel()
FileInfo
+uri: string
+relativePath: string
+fileName: string
+mode: int32_t
+size: int64_t
+mtime: int64_t
+mimeType: string
+Marshalling()
+ReadFromParcel()
+Unmarshalling()
RootInfo
+deviceType: int32_t
+uri: string
+relativePath: string
+displayName: string
+deviceFlags: int32_t
+Marshalling()
+ReadFromParcel()
+Unmarshalling()
Result
+sourceUri: string
+destUri: string
+errCode: int32_t
+errMsg: string
+Marshalling()
+ReadFromParcel()
+Unmarshalling()
ObserverContext
-obs_: sptr<IFileAccessObserver>
-ref_: atomic<int32_t>
-notifyMap_: unordered_map
+Ref()
+UnRef()
+IsValid()
+EqualTo()
ObserverNode
-parent_: shared_ptr<ObserverNode>
-children_: vector<shared_ptr>ObserverNode<>
-obsCodeList_: vector<uint32_t>
-needChildNote_: bool
+FindAndRmObsCodeByCode()
+CheckObsCodeListNotEmpty()

2.5 模块内部依赖框图

工具类
接口层
用户文件服务模块内部结构
FileInfo
RootInfo
Result
FileFilter
JS API
Native API
C API
Picker API
FileAccessService
FileAccessExtAbility
ObserverContext
ObserverNode
Extension管理
权限验证
IPC通信
定时器管理

3. 模块间交互

3.1 交互描述

与系统模块的交互：

  • 权限管理：通过AccessToken模块验证文件访问权限
  • 系统能力管理：通过SAMGR注册为系统能力，提供全局服务
  • 进程间通信：通过IPC机制与Extension和客户端通信
  • 应用框架：通过AAFwk管理Extension生命周期
  • 事件系统：通过CommonEvent处理系统级文件变化事件
  • 存储管理：与StorageService协作管理存储设备

外部库依赖：

  • 系统框架：SAMGR、SAFWK、AAFwk等系统框架
  • IPC框架：支持跨进程通信的IPC机制
  • 权限框架：AccessToken权限验证框架
  • 工具库：cJSON、c_utils等基础工具库
  • 日志框架：HiLog日志记录框架

异步处理机制：

  • 使用NAPI异步工作队列处理JS回调
  • 通过IPC异步机制处理跨进程请求
  • 采用观察者模式处理文件变化通知
  • 支持多线程并发处理文件操作请求

3.2 事件驱动机制

事件类型：

  • NOTIFY_ADD - 文件添加事件
  • NOTIFY_DELETE - 文件删除事件
  • NOTIFY_MOVE_TO - 文件移动到事件
  • NOTIFY_MOVE_FROM - 文件移动出事件
  • NOTIFY_MOVE_SELE - 文件自身移动事件
  • NOTIFY_DEVICE_ONLINE - 设备上线事件
  • NOTIFY_DEVICE_OFFLINE - 设备下线事件

事件处理流程：

  1. 注册文件观察者到指定URI
  2. 底层存储服务检测到文件变化
  3. Extension接收变化通知并处理
  4. FileAccessService转发通知给观察者
  5. 观察者回调函数处理事件

3.3 外部依赖框图

应用层
存储服务
系统服务
用户文件服务模块
文件管理器
文件选择器
媒体应用
第三方应用
MediaLibrary
媒体库服务
ExternalFileManager
外部文件管理
StorageService
存储服务
AppFileService
应用文件服务
SAMGR
系统能力管理
AAFwk
应用框架
AccessToken
权限管理
IPC
进程间通信
CommonEvent
事件系统
FileAccessService
FileAccessExtAbility
观察者管理

4. 状态机转换图

4.1 状态机模型

用户文件服务模块的状态机包含以下主要状态：

服务状态：

  • STATE_NOT_START - 服务未启动
  • STATE_RUNNING - 服务运行中
  • STATE_STOPPING - 服务停止中
  • STATE_EXIT - 服务已退出

Extension状态：

  • EXT_NOT_CONNECTED - Extension未连接
  • EXT_CONNECTING - Extension连接中
  • EXT_CONNECTED - Extension已连接
  • EXT_DISCONNECTED - Extension已断开

观察者状态：

  • OBS_NOT_REGISTERED - 观察者未注册
  • OBS_REGISTERED - 观察者已注册
  • OBS_NOTIFYING - 正在通知观察者
  • OBS_UNREGISTERED - 观察者已注销

文件操作状态：

  • OP_IDLE - 操作空闲
  • OP_IN_PROGRESS - 操作进行中
  • OP_SUCCESS - 操作成功
  • OP_FAILED - 操作失败

4.2 状态切换规则

服务启动流程：

  1. 系统启动时，服务处于STATE_NOT_START状态
  2. 收到启动事件后，进入STATE_RUNNING状态
  3. 初始化Extension管理和观察者管理
  4. 注册到系统能力管理器

Extension连接流程：

  1. 收到连接请求时，从EXT_NOT_CONNECTED进入EXT_CONNECTING状态
  2. 连接成功后，进入EXT_CONNECTED状态
  3. 连接失败或断开时，回到EXT_NOT_CONNECTED状态

观察者注册流程：

  1. 收到注册请求时，从OBS_NOT_REGISTERED进入OBS_REGISTERED状态
  2. 文件变化时，进入OBS_NOTIFYING状态
  3. 通知完成后，回到OBS_REGISTERED状态
  4. 注销时，进入OBS_UNREGISTERED状态

文件操作流程：

  1. 收到操作请求时，从OP_IDLE进入OP_IN_PROGRESS状态
  2. 操作成功时，进入OP_SUCCESS状态
  3. 操作失败时，进入OP_FAILED状态
  4. 操作完成后，回到OP_IDLE状态

事件触发条件：

  • 系统启动/停止事件
  • Extension连接/断开事件
  • 文件变化事件
  • 观察者注册/注销事件
  • 文件操作请求事件

4.3 状态机转换图

系统启动
OnStart()
OnStop()
停止完成
重启服务
初始化Extension
连接请求
连接成功
连接失败
连接断开
重新连接
初始化观察者
注册观察者
文件变化
通知完成
注销观察者
重新注册
初始化操作
操作请求
操作成功
操作失败
操作完成
操作完成
NotStarted
Running
Stopping
Exit
ExtNotConnected
ExtConnecting
ExtConnected
ExtDisconnected
ObsNotRegistered
ObsRegistered
ObsNotifying
ObsUnregistered
OpIdle
OpInProgress
OpSuccess
OpFailed
服务运行状态，可以处理
文件操作和观察者管理
Extension连接状态，
可以处理文件操作请求
文件变化通知状态，
支持多观察者并发通知

5. 接口设计

5.1 公共接口

文件操作接口：

打开文件
int OpenFile(const Uri &uri, const int flags, int &fd);
  • 功能：打开指定URI的文件
  • 参数：
    • uri - 文件URI
    • flags - 打开标志（READ、WRITE、WRITE_READ）
    • fd - 输出参数，文件描述符
  • 返回值：操作结果码
  • 异常处理：URI无效时返回错误码
创建文件
int CreateFile(const Uri &parent, const std::string &displayName, Uri &newFile);
  • 功能：在指定父目录下创建新文件
  • 参数：
    • parent - 父目录URI
    • displayName - 文件名
    • newFile - 输出参数，新文件URI
  • 返回值：操作结果码
  • 权限要求：文件创建权限
删除文件
int Delete(const Uri &sourceFile);
  • 功能：删除指定文件或目录
  • 参数：sourceFile - 要删除的文件URI
  • 返回值：操作结果码
  • 权限要求：文件删除权限
移动文件
int Move(const Uri &sourceFile, const Uri &targetParent, Uri &newFile);
  • 功能：将文件移动到目标父目录
  • 参数：
    • sourceFile - 源文件URI
    • targetParent - 目标父目录URI
    • newFile - 输出参数，新文件URI
  • 返回值：操作结果码
复制文件
int Copy(const Uri &sourceUri, const Uri &destUri, std::vector<Result> &copyResult, bool force = false);
  • 功能：复制文件到目标位置
  • 参数：
    • sourceUri - 源文件URI
    • destUri - 目标URI
    • copyResult - 输出参数，复制结果列表
    • force - 是否强制覆盖
  • 返回值：操作结果码

文件查询接口：

列出文件
int ListFile(const FileInfo &fileInfo, const int64_t offset, const int64_t maxCount,const FileFilter &filter, std::vector<FileInfo> &fileInfoVec);
  • 功能：列出指定目录下的文件
  • 参数：
    • fileInfo - 目录信息
    • offset - 偏移量
    • maxCount - 最大数量
    • filter - 文件过滤器
    • fileInfoVec - 输出参数，文件信息列表
  • 返回值：操作结果码
扫描文件
int ScanFile(const FileInfo &fileInfo, const int64_t offset, const int64_t maxCount,const FileFilter &filter, std::vector<FileInfo> &fileInfoVec);
  • 功能：扫描指定目录下的文件（递归）
  • 参数：同ListFile
  • 返回值：操作结果码
获取根目录
int GetRoots(std::vector<RootInfo> &rootInfoVec);
  • 功能：获取所有可用的根目录信息
  • 参数：rootInfoVec - 输出参数，根目录信息列表
  • 返回值：操作结果码

观察者接口：

注册观察者
int32_t RegisterNotify(const Uri &uri, bool notifyForDescendants, const sptr<IFileAccessObserver> &observer,const ConnectExtensionInfo& info);
  • 功能：注册文件变化观察者
  • 参数：
    • uri - 观察的URI
    • notifyForDescendants - 是否包含子目录
    • observer - 观察者对象
    • info - 连接信息
  • 返回值：操作结果码
注销观察者
int32_t UnregisterNotify(const Uri &uri, const sptr<IFileAccessObserver> &observer,const ConnectExtensionInfo& info);
  • 功能：注销文件变化观察者
  • 参数：同RegisterNotify
  • 返回值：操作结果码

5.2 数据交换接口

IPC接口定义：

  • 使用IDL定义跨进程接口
  • 支持Parcelable对象序列化
  • 提供异步回调机制

数据格式：

  • FileInfo、RootInfo、Result等结构体支持序列化
  • 使用MessageParcel进行数据传递
  • 支持大数据量的共享内存传输

5.3 接口调用时序图

应用程序FileAccessClientFileAccessServiceFileAccessExtAbility存储服务观察者OpenFile(uri, flags)OpenFile(uri, flags)OpenFile(uri, flags)打开文件返回文件描述符返回结果返回结果返回文件描述符RegisterNotify(uri, observer)RegisterNotify(uri, observer)注册观察者注册成功文件变化通知OnChange(uri, type)OnChange(notifyMessage)文件变化回调UnregisterNotify(uri, observer)UnregisterNotify(uri, observer)注销观察者注销成功应用程序FileAccessClientFileAccessServiceFileAccessExtAbility存储服务观察者

6. 总结

用户文件服务模块是OpenHarmony系统中文件管理框架的核心组件，通过统一的FileAccessFramework接口为应用提供文件访问能力。该模块采用Extension机制支持不同存储提供者的插件化接入，通过观察者模式实现文件变化通知，使用异步处理机制提高系统性能。

主要特点：

  • 统一的文件访问接口设计
  • 支持多种存储类型的扩展
  • 完善的文件变化通知机制
  • 安全的权限控制体系
  • 高性能的异步处理能力

技术优势：

  • 模块化架构设计，易于扩展和维护
  • 完善的错误处理和异常管理
  • 支持多语言接口（JS、Native、C）
  • 高效的跨进程通信机制
  • 灵活的观察者模式实现
http://www.dtcms.com/a/418358.html

相关文章：

  • 网站建设早会说什么建设一个网站的需求分析
  • [C++项目组件]cpp-httplib与 websocketpp的简单介绍和使用
  • 奈奎斯特采样定理
  • 做购物网站需要什么服务器网站设计 手写
  • uniapp 使用towxml
  • Uniapp 开发中遭遇「可选链赋值」语法陷阱：一次编译错误排查实录
  • 鸿蒙 H5 环境下的 UniApp 跨域与存储兼容性问题排查
  • 旧vue3项目集成electron
  • Nature Electronics：卡内基梅隆大学开放用于多模态皮肤反馈的皮肤贴附式触觉接口
  • uniapp div区域长按下载到手机相册为照片
  • Electron 安全实践：渲染进程如何安全使用主进程的三方库能力
  • uniapp集成原生安卓开发的插件
  • 做网站建设需要做哪些工作室Wordpress 转发后查看
  • Kafka面试精讲 Day 24：Spring Kafka开发实战
  • 网站模板 站长之家网站开发需要准备什么
  • bat自动保存论文到制定目录
  • 智能化生产+技术壁垒构建食品容器领军者新天力的上市答卷
  • Qt自定义圆环比例控件
  • 第三方软件测试机构:Appium如何使用Selenium的客户端库？
  • Scikit-learn Python机器学习 - 聚类分析算法 - Agglomerative Clustering（凝聚层次聚类）
  • 便宜的自制 30 MHz - 6 GHz 矢量网络分析仪
  • Meta Ray-Ban Display眼镜将引领AR眼镜的智能化应用落地
  • C++篇 Vector模拟实现（1） 初始化 迭代器遍历 插入尾插尾删 一文详解
  • 学习日报 20250928｜React 中实现 “实时检测”：useEffect 依赖项触发机制详解
  • 怎么样可以做自己的网站做网站投注代理犯罪吗
  • 网站空间是服务器吗成都网站设计建设推荐
  • 基于 LangGraph 框架实现智能研究助手示例程序
  • 常用网络命令
  • 实验指导-基于阿里云函数计算的简单邮件发送服务 之数据库访问中间件
  • PPO算法