文件传输通用定义

文件传输IO定义与帧结构 | TUTK P2P SDK 开发指南

一、IO枚举定义

包含协议类型、文件类型、IO控制命令类型的枚举定义，用于文件传输过程中的参数标识和命令交互。

1.1 协议类型枚举（TKProtocol）

typedef enum {
    TK_PROTOCOL_AVAPIs = 0,  // AVAPIs 协议
    TK_PROTOCOL_RDTAPIs      // RDTAPIs 协议
} TKProtocol;

说明：指定文件传输所使用的底层协议，需根据SDK配置和传输需求选择。

1.2 文件类型枚举（FILE_TYPE）

typedef enum {
    TYPE_ALL = 0,  // 所有类型文件
    TYPE_VIDEO,    // 视频文件
    TYPE_AUDIO,    // 音频文件
    TYPE_IMAGE     // 图片文件
} FILE_TYPE;

说明：用于文件列表查询时筛选特定类型的文件，减少数据传输量。

1.3 IO控制命令类型枚举（IOCTRL_TYPE）

typedef enum {
    IOCTRL_FILEMANAGER_FILE_LIST_REQ = 0x9021,    // 文件列表查询请求
    IOCTRL_FILEMANAGER_FILE_LIST_RESP = 0x9022,   // 文件列表查询响应
    IOCTRL_FILEMANAGER_FILE_DOWNLOAD_REQ = 0x9023,// 文件下载请求
    IOCTRL_FILEMANAGER_FILE_DOWNLOAD_RESP = 0x9024,// 文件下载响应
    IOCTRL_FILEMANAGER_FILE_DELETE_REQ = 0x9025,  // 文件删除请求
    IOCTRL_FILEMANAGER_FILE_DELETE_RESP = 0x9026, // 文件删除响应
    IOCTRL_FILEMANAGER_FILE_UPLOAD_REQ = 0x9027,  // 文件上传请求
    IOCTRL_FILEMANAGER_FILE_UPLOAD_RESP = 0x9028, // 文件上传响应
} IOCTRL_TYPE;

说明：文件管理相关的IO控制命令码，请求与响应命令一一对应，用于客户端与设备端的交互同步。

二、IO结构体定义

包含时间、请求参数、响应数据等结构体定义，用于文件传输过程中的数据封装和交互。

2.1 时间结构体（stDateTime）

typedef struct {
    unsigned short year;   // 年（如：2025）
    unsigned char month;   // 月（1-12）
    unsigned char day;     // 日（1-31）
    unsigned char wday;    // 星期（0-6，0表示周日）
    unsigned char hour;    // 时（0-23）
    unsigned char minute;  // 分（0-59）
    unsigned char second;  // 秒（0-59）
} stDateTime;

说明：存储文件的创建/修改时间或查询时间范围，采用UTC时间标准，避免时区差异问题。

2.2 文件列表查询请求结构体（stFileListReq）

typedef struct {
    unsigned int channel;      // 通道号
    stDateTime begin;          // 查询开始时间（UTC时间）
    stDateTime end;            // 查询结束时间（UTC时间）
    int fileType;              // 文件类型（参考 FILE_TYPE 枚举）
    unsigned char reserved[4]; // 预留字段，用于扩展
} stFileListReq;

说明：客户端发送文件列表查询时的请求参数，支持按通道、时间范围、文件类型筛选。

2.3 文件信息结构体（stFileInfo / stFileInfoEx）

// 基础文件信息结构体
typedef struct {
    char fileName[64];  // 文件名（含扩展名，最大长度63字节）
} stFileInfo;

// 扩展文件信息结构体
typedef struct {
    unsigned int iotcChannelId; // IOTC通道ID
    unsigned int fileIndex;     // 文件索引（用于标识唯一文件）
    char fileName[64];          // 文件名（含扩展名）
    unsigned int fileSize;      // 文件大小（单位：字节）
} stFileInfoEx;

说明：stFileInfo 用于简单文件信息传输（如查询响应），stFileInfoEx 包含更多细节（如通道ID、文件大小），适用于下载/上传场景。

2.4 通道信息结构体（stChannelInfo）

typedef struct {
    uint iotcChanelId;  // IOTC通道ID（注意：字段名拼写为 Chanel，与标准 Channel 一致）
} stChannelInfo;

说明：存储文件传输所使用的IOTC通道ID，用于多通道传输时的通道管理。

注意：字段名拼写为 iotcChanelId（单 'n'），实际使用时需与SDK定义保持一致。

2.5 文件列表查询响应结构体（stFileListResp）

typedef struct {
    int total;     // 本次查询的文件总数（可能分多包发送）
    int index;     // 当前包序号（从0开始）
    int count;     // 本包包含的文件数量
    int endflag;   // 结束标志：0=非最后一包，1=最后一包
    stFileInfo files[0]; // 变长数组，存储文件信息列表
} stFileListResp;

说明：设备端返回的文件列表响应，支持大数量文件分包传输，客户端需根据 index 和 endflag 拼接完整列表。

2.6 上传/下载/删除请求结构体（stFileDownloadReq 等）

// 文件下载请求结构体
typedef struct {
    int count;          // 待下载文件数量
    stFileInfo files[0];// 待下载文件信息列表
} stFileDownloadReq;

// 文件删除请求结构体（与下载请求结构一致）
typedef struct {
    int count;          // 待删除文件数量
    stFileInfo files[0];// 待删除文件信息列表
} stFileDeleteReq;

// 文件上传请求结构体（与下载请求结构一致）
typedef struct {
    int count;          // 待上传文件数量
    stFileInfo files[0];// 待上传文件信息列表
} stFileUploadReq;

说明：上传、下载、删除请求结构体结构一致，通过 IOCTRL_TYPE 命令码区分操作类型，支持批量文件操作。

2.7 上传/下载/删除响应结构体（stFileDownloadResp 等）

// 文件下载响应结构体
typedef struct{
    int protocol;  // 使用的传输协议（参考 TKProtocol 枚举）
    int count;     // 成功分配的通道数（-1表示失败）
    stChannelInfo channels[0]; // 传输通道列表
} stFileDownloadResp;

// 文件上传响应结构体（与下载响应结构一致）
typedef struct{
    int protocol;  // 使用的传输协议
    int count;     // 成功分配的通道数（-1表示失败）
    stChannelInfo channels[0]; // 传输通道列表
} stFileUploadResp;

// 文件删除响应结构体
typedef struct {
    int result;    // 操作结果：0=成功，非0=失败（具体错误码参考SDK文档）
} stFileDeleteResp;

说明：stFileDownloadResp / stFileUploadResp 返回传输协议和分配的通道ID，stFileDeleteResp 仅返回操作结果状态。

三、AVAPIs 帧定义

AVAPIs 协议中，文件传输的数据包与包头分开发送，需单独填充包头信息（FRAMEINFO_FOR_UPLOAD_DOWNLOAD_t）和数据缓冲区。

typedef struct {
    char fileName[64];  // 文件名（含扩展名，与请求中的文件名一致）
    unsigned int fileSize;// 文件总大小（单位：字节）
    unsigned int frmSize;// 当前帧数据大小（单位：字节）
    char endFlag;       // 结束标志：1=最后一包，其余=非最后一包
    char reserved[3];   // 预留字段，默认填充0
} FRAMEINFO_FOR_UPLOAD_DOWNLOAD_t;

关键说明：

1. 每帧数据都需携带该包头，用于设备端/客户端解析文件信息和拼接数据；

2. 若同一通道传输多个文件，仅最后一个文件的最后一包设置 endFlag=1，其余所有包（含前序文件的最后一包）均为 0；

3. frmSize 需与实际发送的二进制数据长度一致，避免数据解析错误。

四、RDTAPIs 帧定义

RDTAPIs 协议的文件传输帧分为三部分：数据头 + 二进制数据 + 数据尾，帧结构固定，需严格按格式填充。

图 1：RDTAPIs 文件传输帧结构示意图

各字段详细定义：

frmBegin：4字节，起始标识，固定为字符串 "IOTC"（ASCII码：0x49 0x4F 0x54 0x43）；
fileName：64字节，文件名（含扩展名），不足64字节的部分需用0填充，最大支持63字节有效文件名；
fileSize：4字节，文件总大小（单位：字节），采用大端序存储；
dataLength：4字节，当前数据包的二进制数据长度（单位：字节），需与实际数据部分长度一致；
endFlag：1字节，结束标志：1=当前通道最后一个文件的最后一包，其余=非结束包；
binary data：变长数据，长度为 dataLength 字节，存储文件二进制数据；
frmEnd：2字节，帧结束标识，固定为字符串 "GC"（ASCII码：0x47 0x43）。

关键注意事项

1. 字段长度限制：所有文件名相关字段（fileName）最大长度为64字节（含结束符），实际文件名需控制在63字节内，避免溢出；

2. 时间格式：stDateTime 采用 UTC 时间，需确保客户端与设备端时间同步，避免查询时间范围偏差；

3. 多包传输：文件列表数量较多时，需通过 stFileListResp 的 index 和 endflag 拼接完整列表，避免遗漏文件；

4. 结束标志：AVAPIs 和 RDTAPIs 的 endFlag 规则一致，多文件传输时需严格遵守"仅最后一个文件的最后一包置1"的规则；

5. 字段拼写：stChannelInfo 中的 iotcChanelId 为 SDK 固定定义，实际开发时需直接引用，不可自行修改字段名。