文件系统接口设计说明文档

📎 原始文档：https://www.kdocs.cn/l/clKBOjWFPMAr

文件系统接口设计说明书

Zhuhai Jieli Technologyco.,LTD

版权所有，未经许可，禁止外传

版权所有，侵权必究 1
地址：珠海市吉大石花西路 107号9栋综合楼邮编：519015
电话：0756-6313088 传真：0756-6313081
网站：www.zh-jieli.com

修改记录

版本	更新日期	描述
V1.0
V1.1

版权所有，侵权必究 2
目录
1.文档介绍........................................................................................................................................................................4
1.1.文档目的............................................................................................................................................................ 4
1.2.参考文献............................................................................................................................................................ 4
1.3.术语与缩写词.....................................................................................................................................................4
2.功能概述........................................................................................................................................................................4
3.其他系统/模块的调用关系............................................................................................................................................4
4.性能要求........................................................................................................................................................................4
5.接口模块功能介绍........................................................................................................................................................ 5
5. 1.文件浏览............................................................................................................................错误！未定义书签。
5.1.1.功能介绍................................................................................................................................................5
5.1.2.接口介绍................................................................................................................................................5
5.2.文件删除............................................................................................................................错误！未定义书签。
5.2. 1.实现介绍.............................................................................................................错误！未定义书签。
5.2.2.接口介绍................................................................................................................................................5
5.3.滑动杆...............................................................................................................................错误！未定义书签。
5.3.1.功能介绍................................................................................................................................................6
5.3.2.接口........................................................................................................................................................6
5.4.消息处理............................................................................................................................错误！未定义书签。
5.4.1.功能介绍................................................................................................................................................6
5.4.2.接口........................................................................................................................................................7
5.5.资源文件处理....................................................................................................................错误！未定义书签。
5.5.1.功能介绍................................................................................................................................................7
5.5.2.接口介绍................................................................................................................................................7
5.6.菜单列表............................................................................................................................错误！未定义书签。
5.6.1.功能介绍................................................................................................................................................8
5.6.2.接口介绍................................................................................................................................................8
5.7.进度条...............................................................................................................................错误！未定义书签。
5.7.1.功能介绍................................................................................................................................................9
5.7.2.接口介绍................................................................................................................................................9
5.8.滚动条................................................................................................................................................................ 9
5.8.1.功能介绍.............................................................................................................................................. 11
5.8.2.接口介绍.............................................................................................................................................. 11
5.9.出错提示............................................................................................................................错误！未定义书签。
5.9.1.功能介绍.............................................................................................................................................. 11
5.9.2.接口介绍.............................................................................................................................................. 11
6. COMMON链接地址空间............................................................................................................错误！未定义书签。
版权所有，侵权必究 3

1.文档介绍

1.1.文档目的

说明文件系统相关接口使用和作用，帮助AP开发人员方便使用提供的接口。

1.2.参考文献

[ 1] .

1.3.术语与缩写词

缩写、术语	解释
AP	Application,应用程序

2.功能概述

文件系统接口模块主要提供包含文件浏览，文件删除，打开，创建，读写，等接口给AP应用调用。

3.其他系统/模块的调用关系

音乐，录音，解码等模式会使用到。

4.性能要求

传入正确的参数。
版权所有，侵权必究 4
地址：珠海市吉大石花西路 107号9栋综合楼邮编：519015
电话：0756-6313088 传真：0756-6313081
网站：www.zh-jieli.com

5.接口模块功能介绍

5.1.挂载设备

5.1.1.功能介绍

由设备名、路径、文件系统类型来挂载设备和文件系统

5.1.2.接口介绍

函数原型	struct imount mount(const char dev_name, const char path, const char fs_type, int cache_num, void *dev_arg); //挂载
功能描述	挂载设备
参数说明	dev_name// 设备名字 Path //路径 fs_type// 文件系统类型 cache_num // 缓存数目 dev_arg//设备参数
输出	* \return mt结构句柄
例子	void *fmnt = mount(p->name, p->storage_path, p->fs_type, 3, NULL);
关联模块	dev_manager.c
补充说明	注意路径和文件系统类型选择

5.2.卸载设备

5.2.1.功能介绍

卸载设备

5.2.2.接口介绍

函数原型	int unmount(const char *path);
功能描述	卸载设备
参数说明	Path //路径
输出	* \return 返回相应的操作消息处理值 0为成功
例子	unmount(dev->parm->storage_path);


关联模块	dev_manager.c
补充说明

5.3.格式化

5.3.1.功能介绍

格式化设备。

5.3.2.接口介绍

函数原型	int f_format(const char path, const char fs_type, u32 clust_size); //格式化接口
功能描述	格式化设备
参数说明	path// 路径 fs_type// 文件系统类型 clust_size// 簇大小
输出	* \return 0格式化成功，非0 失败
关联模块
例子	result =f_format(“storage/sd0/C/”,“fat”, 32* 1024);
补充说明	~~暂时只支持fat32得格式化~~

5.4.文件打开

5.4.1. 功能介绍

/* ---------------------------------------------------------------------------- /
/* @brief:
@param: fopen 扩展功能
@note: fopen 自动打开、创建文件夹和文件。
说明：
1.设备路径+文件，其中文件传入格式:"music/test/1/2/3/pk* .wav" "JL_REC/AC69**** .wav""JL_REC/AC690000 .wav"
2.文件名带号，带多少个表示多少个可变数字，最多为8+3 的大小，如表示可变数字名称变为 XXX0001,XXXX002这样得格式，不带*号则只创建一个文件，写覆盖。
@date: 2020-07-22
版权所有，侵权必究 6
/
/ ---------------------------------------------------------------------------- */。

5.4.2.接口介绍

函数原型	FILE fopen(const char path, const char *mode);
功能描述	打开文件
参数说明	Path// 文件名路径 Mode //打开模式（只读，写，可创建）
输出	* \return 返回获得得文件句柄
关联模块	/encode_write_file.c， app_config.c， audio_dec_record.c
例子	record_file = fopen(path, "r") ;
补充说明	注意路径需要带上根路径

函数原型	int fread(FILE file, void buf, u32 len);
功能描述	读资源文件
参数说明	File// 文件句柄 Buf// 读出内容放置buf Len // 需要读出内容得长度（一般为buf长度）
输出	返回读出得长度
关联模块	app_config.c， norflash_update.c， audio_dec_file.c
例子	rlen = fread(dec->file, buf, len);
补充说明

函数原型	int fwrite(FILE file, void buf, u32 len);
功能描述	写资源文件
参数说明	File// 文件句柄 Buf// 写入得内容放置buf Len // 需要写入内容得长度（一般为buf长度）
输出	返回写入得长度
关联模块	encode_write_file.c
例子	ret = fwrite(wfil- >file, frame, len);
补充说明

函数原型	int fseek(FILE *file, int offset, int orig);
功能描述	Seek到相应得位置
参数说明	File//文件句柄 Offset// 偏移量 Orig// 偏移方式
输出	* \return 返回偏移得值
关联模块	encode_write_file.c
例子	fseek(wfil- >file, 0, SEEK_SET);
补充说明	~~偏移方式 #define SEEK~~_~~SET 0 /~~* ~~Seek ~~~~ from ~~~~beginning of~~ ~~file~~.~~ */~~

	~~#define SEEK~~~~CUR 1 /~~* ~~Seek ~~~~ from ~~~~ current~~ ~~position~~.~~ / #define SEEK~~~~END 2 /~~ ~~Seek from end of~~ ~~file~~.~~ */~~

函数原型	int flen(FILE *file);
功能描述	获取文件长度
参数说明	File//文件结构.
输出	* \return 当前文件长度
关联模块	audio_dec_file.c
例子	len = flen(dec->file);
补充说明

函数原型	int fpos(FILE *file);
功能描述	获取文件指针位置
参数说明	File//文件结构.
输出	* \return 当前文件指针位置

关联模块	/encode_write_file.c, music_id3 .c
例子	u32 cur_fptr = fpos(file);
补充说明

函数原型	int fclose(FILE *file);
功能描述	关闭文件
参数说明	File //文件结构.
输出	* \return 无意义
关联模块	/encode_write_file. c, /app_config.c
例子	fclose(wfil- >file);
补充说明	关闭后，将file=NULL 避免成为野指针

函数原型	int fdelete(FILE *file);
功能描述	删除文件
参数说明	File //文件结构.
输出	* \return 无意义
关联模块	/encode_write_file. c, music_player.c
例子	fdelete(wfil- >file);


补充说明	删除后，将file=NULL 避免成为野指针

函数原型	int fget_name(FILE file, u8 name, int len);
功能描述	获取当前文件名称，支持长短文件名。
参数说明	File //文件结构. Name //文件名buf Len //长度
输出	* \return 获取到的文件名长度
关联模块	music_func.c， audio_dec_tone.c
例子	int lfn_len = fget_name(file, lfn_buf, 512);
补充说明	Buf最好足够大，传入len < 16时，默认只获取短文件名

函数原型	int fget_name_type(char *path, int len); //判断是不是unicode码
功能描述	判断是不是unicode码
参数说明	Path //文件名buf 究

	Len //文件名长度
输出	* \return * \retval TRUE 是Unicode * \retval FALSE 不是
关联模块	music_func.c
例子	int unicode = fget_name_type(lfn_buf, lfn_len);
补充说明

函数原型	struct vfscan fscan(const char path, const char *arg, u8 max_deepth);
功能描述	文件扫描
参数说明	Path //路径 Arg //s扫描方式 max_deepth // 扫描深度，最大为9
输出	* \return vfscan句柄
关联模块	dev_manager.c
例子	fsn = fscan(fopr->fsn_path, sel- >scan_type, 9);
补充说明	/* arg: * -t 文件类型 * -r 包含子目录 * -d 扫描文件夹 * -a 文件属性 r: 读， /: 非 * -s 排序方式， t:按时间排序， n:按文件号排序 */

函数原型	struct vfscan fscan_interrupt(const char path, const char arg, u8 max_deepth, int ( callback)(void)); //可打断扫描
功能描述	文件扫描，可打断
参数说明	Path //路径 Arg //s扫描方式 max_deepth // 扫描深度，最大为9 Callback ///回调函数，用于打断
输出	* \return vfscan句柄
关联模块	dev_manager.c
例子	fsn = fscan_interrupt((const char *)fsn_path, parm, DEV_MANAGER_SCAN_DISK_MAX_DEEPTH, callback);
补充说明	回调函数返回 1则打断

函数原型	struct vfscan fscan_enterdir(struct vfscan fs, const char *path);
功能描述	/进入指定子目录，只扫此目录下文件信息
参数说明	Fs //VFScan 句柄 Path //子目录句柄 w
输出	究* \return 相应的句柄 13

关联模块	jlfat_api.c
例子	fsn = fscan_enterdir(fsn, loop_str);
补充说明	支持相对路径

函数原型	struct vfscan fscan_exitdir(struct vfscan fs);
功能描述	返回上一层目录
参数说明	Fs //VFScan 句柄
输出	* \return 相应的句柄
关联模块	jlfat_api.c
例子	fsn = fscan_exitdir(fsn);
补充说明

函数原型	void fscan_release(struct vfscan *fs);
功能描述	释放句柄
参数说明	Fs //VFScan句柄
输出	* \return 无
关联模块	dev_manager.c
例子	fscan_release(fsn);
补充说明	究 14

函数原型	FILE fselect(struct vfscan fs, int selt_mode, int arg); //选择指定文件
功能描述	选择指定文件打开
参数说明	Fs ///VFSCAN 句柄 selt_mode // 按什么方式选择 Arg /// 传入选择的参数
输出	* \return 文件句柄
关联模块	music_player.c
例子	__this->file = fselect(__this->fsn, FSEL_PREV_FILE, 0);///选择上一曲
补充说明	支持，按簇号、序号、路径选择

函数原型	int fdir_exist(const char *dir); /
功能描述	检查挂载目录是否存在
参数说明	Dir ///目录路径
输出	* \return 0存在， 1不存在
关联模块	究无 15

例子	Int exist = fdir_exist(dir)
补充说明

函数原型	int fget_attr(FILE file, int attr);
功能描述	获取文件属性
参数说明	File // 文件句柄 Attr //属性
输出	* \return 获取值在attr 中
关联模块	jlfat_api.c
例子	fget_attr(file, &attr);
补充说明	传入指针进去

函数原型	int fset_attr(FILE file, int attr);
功能描述	设置文件属性
参数说明	File // 文件句柄 Attr //属性
输出	* \return 设置值在attr 中
关联模块
例子	fset_attr(file, attr);
补充说明

函数原型	int fget_attrs(FILE file, struct vfs_attr attr);//获得文件相关信息如属性、簇号、大小等
功能描述	获取文件相关信息
参数说明	File // 文件句柄 Attr //记录相应信息的结构体
输出	* \return 获取值在attr 中
关联模块	encode_write_file.c， music_player.c， /custom_cfg.c
例子	fget_attrs( this->file, &attr);
补充说明	传入结构体指针进去

函数原型	struct vfs_partition fget_partition(const char path);
功能描述	获取分区part
参数说明	Path //路径
输出	* \return vfs_partition句柄
关联模块
例子	struct vfs_partition part = fget_partition(path); 17

补充说明

函数原型	int fget_folder(struct vfscan fs, struct ffolder arg); //获取文件夹序号和文件夹内文件数目
功能描述	获取文件夹信息
参数说明	Fs ///vfscan 结构句柄 Arg // 文件夹信息结构句柄
输出	* \return 文件夹信息结构句柄
关联模块
例子	fget_folder(fopr->fsn, &folder);
补充说明

函数原型	int fset_lfn_buf(struct vfscan fs, void arg);//设置长文件名buf
功能描述	设置长文件名Buf
参数说明	Fs //vfscan 句柄 Arg // buf
输出	* \return
关联模块	/dev_manager.c
例子	fset_lfn_buf(fsn, dev->lfn_buf);
补充说明

函数原型	int fset_ldn_buf(struct vfscan fs, void arg);//设置长文件名buf
功能描述	设置长文件夹名Buf
参数说明	Fs //vfscan 句柄 Arg // buf
输出	* \return
关联模块
例子	fset_ldn_buf(fopr->fsn, ldn_buf);
补充说明

函数原型	int fset_ext_type(const char path, void ext_type);//设置后缀类型
功能描述	设置后缀类型
参数说明	Path // 路径 ext_type // 后缀类型
输出	* \return 0成功，非0不成功
关联模块	file_bs_deal.c
例子	fset_ext_type(dev_manager_get_bs_root_path(fil_bs->dev), ext_name);
补充说明

函数原型	int fopen_dir_info(const char path, FILE pp_file, void dir_dj);
功能描述	打开目录
参数说明	Path // 路径 pp_file /// 文件句柄 Dir_dj //目录信息句柄
输出	* \return 目录项总数
关联模块	file_bs_deal.c
例子	total_dir = fopen_dir_info(dev_manager_get_bs_root_path(fil_bs->dev), &fil_bs->file, 0);
补充说明

函数原型	int fenter_dir_info(FILE file, void dir_dj); //进入目录
功能描述	进入目录
参数说明	Path // 路径 pp_file /// 文件句柄 Dir_dj //目录信息句柄
输出	* \return 目录项总数
关联模块	file_bs_deal.c
例子	total_dir = fenter_dir_info(fil_bs->file, dir_info); //使用open获得的file，无需重新申请。
补充说明

函数原型	int fexit_dir_info(FILE *file); //退出
功能描述	退出目录
参数说明	file /// 文件句柄
输出	* \return 目录项总数
关联模块	file_bs_deal.c
例子	total_dir = fexit_dir_info(fil_bs->file);//
补充说明

函数原型	int fget_dir_info(FILE file, u32 start_num, u32 total_num, void buf_info);
功能描述	获取目录信息
参数说明	file /// 文件句柄 start_num //起始位置 total_num // 获取目录个数 Buf_info //目录信息句柄
输出	* \return 获取的目录数
关联模块	file_bs_deal.c
例子	real_dir = fget_dir_info(fil_bs->file, start_sn, get_cnt, buf);
补充说明

函数原型	int fget_file_byname_indir(FILE file, FILE newFile, void ext_name); //由歌曲名称获得歌词
功能描述	由歌曲名称获取歌词
参数说明	file /// 歌曲文件句柄 newFile // 歌词文件句柄 ext_name // 后缀名称
输出	* \return 0找到了， 1 没找到
关联模块	lyrics_api.c
例子	find_lrc_flag = fget_file_byname_indir(file, newFile, ext_name);
补充说明

函数原型	int fget_disp_info(FILE file, void arg); //用于长文件名获取
功能描述	获取长文件名和长文件夹名信息
参数说明	file /// 歌曲文件句柄 Arg //长文件相关信息结构指针
输出	* \return 0成功，非0不成功
关联模块	music_action.c
例子	fget_disp_info(file, & this->fs_info);
补充说明	究 22

函数原型	int fmk_dir(const char path, char folder, u8 mode);
功能描述	创建目录
参数说明	Path //路径 Folder // 文件夹名称 Mode //目录属性
输出	* \return 0成功，非0不成功
关联模块
例子	fmk_dir(path, folder, 0);
补充说明

函数原型	int fget_encfolder_info(const char path, char folder, char ext, u32 last_num, u32 *total_num) ; //获取录音文件信息
功能描述	获取录音文件信息
参数说明	Path //路径 Folder // 文件夹名称 Ext //文件名后缀 last_num // 可变数字最大数字 total_num //文件总数
输出	* \return 0成功，非0不成功
关联模块
例子	究ret = fget_encfolder_info(path, folder, ext, &last_num, &total_num) ; 23


补充说明