文件系统管理
文件系统管理组提供用于向设备上传文件和从设备下载文件的命令。
文件管理组定义以下命令：
|
命令描述 |
|---|---|
|
文件下载/上传 |
|
文件状态 |
|
文件哈希/校验和 |
|
支持的文件哈希/校验和类型 |
|
文件关闭 |
文件下载
该命令允许从目标设备的指定路径下载现有文件的内容。客户端应用程序必须跟踪已下载的数据以及文件中的当前位置（MCUmgr 也会缓存这些信息），并使用修改后的偏移量发出后续请求，以获取整个文件。请求不携带所请求数据块的大小，大小由应用程序本身指定。请注意，对于连续请求，文件句柄将保持打开状态（只要尚未达到空闲超时，并且另一个传输没有使用 fs_mgmt 上传/下载文件），但在下载会话期间，文件并非由 MCUmgr 独占，并且可能在请求之间发生变化甚至被删除。
备注
默认情况下，所有文件上传/下载请求都无条件允许。但是，如果启用了 Kconfig 选项 CONFIG_MCUMGR_GRP_FS_FILE_ACCESS_HOOK，应用程序可以为 MGMT_EVT_OP_FS_MGMT_FILE_ACCESS 注册回调处理程序（参见 MCUmgr 回调），从而允许或拒绝读取/写入特定文件的访问，或者重写客户端提供的路径。
文件下载请求
文件下载请求头：
|
|
|
|---|---|---|
|
|
|
请求的 CBOR 数据：
{
(str)"off" : (uint)
(str)"name" : (str)
}
其中：
"off" |
开始下载的偏移量 |
"name" |
文件的绝对路径 |
文件下载响应
文件下载响应头：
|
|
|
|---|---|---|
|
|
|
成功响应的 CBOR 数据：
{
(str)"off" : (uint)
(str)"data" : (byte str)
(str,opt)"len" : (uint)
}
出错时，CBOR 数据采用以下形式：
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}
{
(str)"rc" : (int)
}
其中：
"off" |
响应对应的偏移量。 |
"data" |
从文件读取的数据块；它是嵌入了大小的 CBOR 编码字节流；只有在 “rc” 为 0 的响应中才会出现 “data”。 |
"len" |
文件长度；仅当 “off” 为 0 时，此字段才是必需的。 |
"err" -> "group" |
|
"err" -> "rc" |
包含基于分组的错误代码的索引。仅在使用 SMP 版本 2 且为非零（错误情况）时出现。 |
"rc" |
|
文件上传
允许将文件上传到指定位置。该命令会自动覆盖现有文件，或者如果指定路径上不存在文件则创建新文件。协议支持无状态上传，其中每个请求携带文件的不同数据块，跟踪上传进度是客户端的责任。
请注意，对于连续请求，文件句柄将保持打开状态（只要尚未达到空闲超时，但文件并非由 MCUmgr 独占，在下载会话期间，文件可能在请求之间发生变化甚至被删除）。请注意，对于连续请求，文件句柄将保持打开状态（只要尚未达到空闲超时，并且另一个传输没有使用 fs_mgmt 上传/下载文件），但文件并非由 MCUmgr 独占，在下载会话期间，文件可能在请求之间发生变化甚至被删除。
备注
奇怪的是，当前 Zephyr 实现是半无状态的，因为它能够保存单个上传上下文，其中包含正在进行的上传的信息，这些信息仅由表示上传进行中的 bool 标志、上次成功上传的偏移量和总长度组成。
备注
默认情况下，所有文件上传/下载请求都无条件允许。但是，如果启用了 Kconfig 选项 CONFIG_MCUMGR_GRP_FS_FILE_ACCESS_HOOK，应用程序可以为 MGMT_EVT_OP_FS_MGMT_FILE_ACCESS 注册回调处理程序（参见 MCUmgr 回调），从而允许或拒绝读取/写入特定文件的访问，或者重写客户端提供的路径。
文件上传请求
文件上传请求头：
|
|
|
|---|---|---|
|
|
|
请求的 CBOR 数据：
{
(str)"off" : (uint)
(str)"data" : (str)
(str)"name" : (str)
(str,opt)"len" : (uint)
}
其中：
"off" |
开始/继续上传的偏移量。 |
"data" |
要写入文件的数据块；它是嵌入了长度的 CBOR 编码。 |
"name" |
文件的绝对路径。 |
"len" |
文件长度；仅当 “off” 为 0 时，此字段才是必需的。 |
文件上传响应
文件上传响应头：
|
|
|
|---|---|---|
|
|
|
成功响应的 CBOR 数据：
{
(str)"off" : (uint)
}
出错时，CBOR 数据采用以下形式：
其中：
"off" |
上次成功写入数据的偏移量。 |
"err" -> "group" |
|
"err" -> "rc" |
包含基于分组的错误代码的索引。仅在使用 SMP 版本 2 且为非零（错误情况）时出现。 |
"rc" |
|
File status
该命令允许从目标设备的指定路径检索现有文件的状态。
文件状态请求
文件状态请求头：
|
|
|
|---|---|---|
|
|
|
请求的 CBOR 数据：
{
(str)"name" : (str)
}
其中：
"name" |
文件的绝对路径。 |
文件状态响应
文件状态响应头：
|
|
|
|---|---|---|
|
|
|
成功响应的 CBOR 数据：
{
(str)"len" : (uint)
}
出错时，CBOR 数据采用以下形式：
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}
{
(str)"rc" : (int)
}
其中：
"len" |
文件长度（以字节为单位）。 |
"err" -> "group" |
|
"err" -> "rc" |
包含基于分组的错误代码的索引。仅在使用 SMP 版本 2 且为非零（错误情况）时出现。 |
"rc" |
|
File hash/checksum
该命令允许为位于目标设备指定路径的现有文件生成哈希/校验和。请注意，此功能需要分配内核堆内存作为缓冲区，并且生成输出哈希/校验和需要较大的栈内存缓冲区。基础功能需要启用 CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH 选项；支持的哈希/校验和通过 CONFIG_MCUMGR_GRP_FS_CHECKSUM_IEEE_CRC32 或 CONFIG_MCUMGR_GRP_FS_HASH_SHA256 选择性启用。
文件哈希/校验和请求
文件哈希/校验和请求头：
|
|
|
|---|---|---|
|
|
|
请求的 CBOR 数据：
{
(str)"name" : (str)
(str,opt)"type" : (str)
(str,opt)"off" : (uint)
(str,opt)"len" : (uint)
}
其中：
"name" |
文件的绝对路径。 |
"type" |
要执行的哈希/校验和类型（参见 哈希/校验和类型），省略则使用默认值。 |
"off" |
开始哈希/校验和计算的偏移量（可选，未提供时为 0）。 |
"len" |
为生成哈希/校验和而从文件读取的最大数据长度（可选，未提供时为整个文件大小）。 |
哈希/校验和类型
字符串名称 |
哈希/校验和 |
字节字符串 |
大小（字节） |
|---|---|---|---|
|
IEEE CRC32 校验和 |
否 |
4 |
|
SHA256（安全哈希算法） |
是 |
32 |
请注意，如果启用了 crc32，则默认类型为 crc32；如果未启用 crc32，则默认类型为 sha256。
文件哈希/校验和响应
文件哈希/校验和响应头：
|
|
|
|---|---|---|
|
|
|
成功响应的 CBOR 数据：
{
(str)"type" : (str)
(str,opt)"off" : (uint)
(str)"len" : (uint)
(str)"output" : (uint or bstr)
}
出错时，CBOR 数据采用以下形式：
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}
{
(str)"rc" : (int)
}
其中：
"type" |
已执行的哈希/校验和类型（参见 哈希/校验和类型）。 |
"off" |
哈希/校验和计算开始的偏移量（仅在不为 0 时出现）。 |
"len" |
用于生成哈希/校验和的输入数据长度（以字节为单位）。 |
"output" |
输出的哈希/校验和。 |
"err" -> "group" |
|
"err" -> "rc" |
包含基于分组的错误代码的索引。仅在使用 SMP 版本 2 且为非零（错误情况）时出现。 |
"rc" |
|
Supported file hash/checksum types
该命令允许列出设备上可用的哈希和校验和类型。需要启用 CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH_SUPPORTED_CMD 选项。
支持的文件哈希/校验和类型请求
支持的文件哈希/校验和类型请求头：
|
|
|
|---|---|---|
|
|
|
该命令发送空 CBOR 映射作为数据。
支持的文件哈希/校验和类型响应
支持的文件哈希/校验和类型响应头：
|
|
|
|---|---|---|
|
|
|
成功响应的 CBOR 数据：
{
(str)"types" : {
(str)<hash_checksum_name> : {
(str)"format" : (uint)
(str)"size" : (uint)
}
...
}
}
出错时，CBOR 数据采用以下形式：
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}
{
(str)"rc" : (int)
}
其中：
<hash_checksum_name> |
哈希/校验和类型的名称（参见 哈希/校验和类型）。 |
"format" |
哈希/校验和返回的格式，其中 0 表示数值，1 表示字节数组。 |
"size" |
输出哈希/校验和响应的大小（以字节为单位）。 |
"err" -> "group" |
|
"err" -> "rc" |
包含基于分组的错误代码的索引。仅在使用 SMP 版本 2 且为非零（错误情况）时出现。 |
"rc" |
|
File close
该命令允许关闭 fs_mgmt 上传/下载请求持有的、可能已停滞或不完整的任何打开文件句柄。
文件关闭请求
文件关闭请求头：
|
|
|
|---|---|---|
|
|
|
该命令发送空 CBOR 映射作为数据。
文件关闭响应
文件关闭响应头：
|
|
|
|---|---|---|
|
|
|
成功时，该命令发送空 CBOR 映射作为数据。出错时，CBOR 数据采用以下形式：
{
(str)"err" : {
(str)"group" : (uint)
(str)"rc" : (uint)
}
}
{
(str)"rc" : (int)
}
其中：
"err" -> "group" |
|
"err" -> "rc" |
包含基于分组的错误代码的索引。仅在使用 SMP 版本 2 且为非零（错误情况）时出现。 |
"rc" |
|