首页 / knowledge/代码解析/net

afci_download.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 返回值约定 4.2 与状态机的关系 4.3 通信协议 / 定时 / uCOS-II 5. 对外接口 6. 依赖关系 7. 备注与风险点

源文件路径：net/afci_download.h 所属模块：net（网络应用层 / 设备固件升级下载）代码行数：21

1. 文件职责

本文件是 net/afci_download.c 的对外接口头文件，向工程其他模块声明 AFCI（电弧故障断路器）固件升级流程的 5 个查询接口：强制更新标志、是否已完成更新、下载百分比、AFCI 机型串、AFCI 硬件版本号。

它在数据流中处于「升级状态标志的只读出口」位置：net/server.c 与 net/upd_download.c 负责写 g_stEMSInfo.stUpt[UPDT_AFCI]，HMI（hmi/ui/ui_main.c）、云端上报（net/ems.c）、逆变器通信（midware/inverter/alphaess/alphaess_comm_usart.c）通过本头文件提供的原型读取这些状态。

本文件不含任何逻辑、状态或变量，只有 include guard、一个 include 和 5 个函数原型。

2. 关键数据结构与宏

名称	类型	说明
`__AFCI_DOWNLOAD_H__`	宏	include guard（第 9-10 行），防止重复包含
`is_afci_firm_download_finished`	函数原型	`u8 is_afci_firm_download_finished(void)`，定义于 `afci_download.c:59`
`IsDownloadAFCI`	函数原型	`u8 IsDownloadAFCI(void)`，定义于 `afci_download.c:70`
`GetPercentDownloadAFCI`	函数原型	`u8 GetPercentDownloadAFCI(void)`，定义于 `afci_download.c:81`
`get_afci_type`	函数原型	`char* get_afci_type(void)`，定义于 `afci_download.c:93`
`get_afci_hard_version`	函数原型	`char *get_afci_hard_version(void)`，定义于 `afci_download.c:110`

本文件不定义结构体、枚举、联合体、位域，也没有除 include guard 外的任何宏常量。所有类型（u8 等）来自第 12 行 #include <includes.h>。

3. 函数清单

函数名	作用域	说明
`is_afci_firm_download_finished`	全局（原型声明）	查询 AFCI 固件是否已成功从服务器接收并通过 MD5 校验，定义于 `afci_download.c:59`
`IsDownloadAFCI`	全局（原型声明）	查询云端是否下发过 AFCI 强制更新标志，定义于 `afci_download.c:70`
`GetPercentDownloadAFCI`	全局（原型声明）	查询 AFCI 固件下载百分比（0~100），定义于 `afci_download.c:81`
`get_afci_type`	全局（原型声明）	由逆变器机型推导出的 AFCI 机型串，非贝瓦机型返回空串，定义于 `afci_download.c:93`
`get_afci_hard_version`	全局（原型声明）	返回 AFCI 硬件版本常量 `"V1.0"`，定义于 `afci_download.c:110`

共 5 个原型声明，均对应 afci_download.c 中的全局定义；无 static 函数、无函数指针、无回调。

4. 核心逻辑解析

本文件是纯声明文件，不含可执行逻辑。接口契约要点：

4.1 返回值约定

is_afci_firm_download_finished() / IsDownloadAFCI()：返回 u8，实际取值只有 0 / 1（底层是 BOOLEAN 型 bIsUpdatedFromServer / bIsUpdateForce 提升而来），调用方直接当布尔用。
GetPercentDownloadAFCI()：返回 u8，语义是 0~100 的百分数。注意分母可能为 0（文件长度尚未从服务器取得时），详见 afci_download.c.md 备注 3。
get_afci_type()：返回指向常量字符串或空串的 char*，调用方只读、不得释放。
get_afci_hard_version()：同上，返回 afci_comm.h 中的宏常量地址。

4.2 与状态机的关系

本头文件暴露的两个布尔接口刻画了 AFCI 升级的两端：

IsDownloadAFCI()==1                →  服务器已下发强制升级、正在下载（由 server.c 置位）
is_afci_firm_download_finished()==1 →  固件已收妥且 MD5 匹配（由 upd_download.c:412 置位）

中间过程（包序校验、超时重发、MD5 比对）不经过本头文件，全部在 net/server.c 与 net/upd_download.c 内完成。

4.3 通信协议 / 定时 / uCOS-II

均不涉及。本文件不定义帧格式、校验、超时参数，不声明信号量、消息邮箱或任务，也不引用任何 uCOS-II API。所声明的函数都由调用方在自己的任务上下文里同步调用。

5. 对外接口

导出（供外部使用）：

名称	使用方
`is_afci_firm_download_finished`	`midware/inverter/alphaess/alphaess_comm_usart.c:5337`、`:5444`
`IsDownloadAFCI`	`hmi/ui/ui_main.c:898`、`net/ems_download.c:261`
`GetPercentDownloadAFCI`	`hmi/ui/ui_main.c:904`
`get_afci_type`	`net/ems.c:3025`、`:3105`、`net/server.c:3314`、`:3711`
`get_afci_hard_version`	`net/ems.c:2989`、`net/server.c:3314`

被调用（本文件引用的外部符号）：

名称	来源
`includes.h`	第 12 行 `#include <includes.h>`，提供 `u8` / `u32` / `BOOLEAN` 等基础类型，并间接带入 uCOS-II、GD32 外设头文件

本文件不导出任何全局变量，也不引用外部全局变量。

6. 依赖关系

依赖：

UCOSII/uCOS-CONFIG/includes.h（尖括号形式，第 12 行）——唯一依赖，用于取得基础类型定义；
不依赖 ems.h、server.h、upd_download.h 等，因此任何模块都能以极低耦合代价引入它。

被依赖（include 本头文件的文件）：

net/afci_download.c:14
net/ems.c:57、net/ems_download.c:30、net/server.c:54
hmi/ui/ui_main.c:32
midware/inverter/alphaess/alphaess_comm_usart.c:31

7. 备注与风险点

声明集合与实现集合不一致：afci_download.c:41 定义的 get_afci_Updt_File_Mask() 在本头文件中没有声明，因此它对其他编译单元不可见（只能靠隐式声明调用，C99 起会告警）。这个函数目前也无人调用，属于游离符号。
注释中的 @author 与 .c 不一致：本文件写 Alpha g_stEMSInfo Team，afci_download.c 写 Alpha EMS Team。结合 meter_download.h / evc_download.h 也是 g_stEMSInfo 版本，推测是历史上把 EMS 标识符批量替换为 g_stEMSInfo 时误伤了注释。
文件头 @brief 为空：5 个函数中 IsDownloadAFCI、is_afci_firm_download_finished 语义相近（一个是“服务器要求升级”，一个是“升级已完成”），仅看头文件无法区分，调用方必须去读 .c。建议在头文件补一行说明。
get_afci_type() 可能在非贝瓦机型下返回空串：调用方若把返回值直接拼进 JSON 或用于 strstr 比较，需要注意空串的语义（当前 net/server.c:3711、net/ems.c:3025 都未做空串判断，但空串在这两处恰好是“不参与匹配/输出空字段”，行为可接受）。