// file_service.erpc
program file_service

@id(2)
interface file_service
{
    /**
     * @brief 开始一次文件上传会话。
     * @param path 目标文件路径；服务端会先写入 "<path>.part" 临时文件。
     * @param total_size 本次上传的文件总字节数，用于服务端校验最终大小。
     * @return RT_EOK 表示成功；负数表示 RT-Thread/POSIX 错误码。
     */
    fileWriteBegin(string path, uint32 total_size) -> int32

    /**
     * @brief 写入一个文件分块。
     * @param data 当前分块的二进制内容；dataLength 是分块字节数，data 是分块数据指针。
     * @return RT_EOK 表示成功；负数表示 RT-Thread/POSIX 错误码。
     *
     * @note 单个分块会被封装进一次 eRPC 消息，最大可用长度受 ERPC_DEFAULT_BUFFER_SIZE 限制。
     */
    fileWriteChunk(binary data) -> int32

    /**
     * @brief 完成上传会话。
     * @return RT_EOK 表示成功；负数表示 RT-Thread/POSIX 错误码。
     *
     * @note 服务端会先校验已接收字节数是否等于 total_size，然后把临时文件重命名为目标文件。
     */
    fileWriteEnd() -> int32

    /**
     * @brief 取消当前上传会话。
     * @return RT_EOK 表示成功；负数表示 RT-Thread/POSIX 错误码。
     *
     * @note 服务端会关闭当前文件并删除残留的 ".part" 临时文件。
     */
    fileWriteAbort() -> int32
}