Windows C++ 即时通讯大文件上传与断点续传 - 开发者中心

消息类型	3.2.0 之前	3.2.0 及以后	格式与其他要求
文件	100 MB	1 GB	格式不限
视频	100 MB	1 GB	MP4、MOV；需填写播放时长；获取首帧宽高需使用 H.264 或 H.265 编码
音频	6 MB	1 GB	MP3、M4A；时长不超过 300 秒
图片	10 MB	20 MB	支持的格式请参考收发消息

方式	上传与投递行为	下载地址的维护责任
本地文件发送	设置 `fileLocalPath`，SDK 将文件上传至 ZEGO 服务器，生成下载地址并随消息投递	发送成功后从回调的消息对象获取 `fileDownloadUrl`。双方均可用该 URL 下载文件，发送方删除本地文件不影响已发送成功的消息
网络文件直发	设置 `fileDownloadUrl`，SDK 仅透传 URL，不经过 ZEGO 服务器中转，也不生成新的下载地址	业务侧确保 URL 公网可访问，并处理加载失败和链接失效

参数	含义
currentFileSize / totalFileSize	组合消息中所有媒体文件的已上传字节数 / 总字节数
messageInfoIndex	当前媒体文件在组合消息内容中的索引
currentIndexFileSize / totalIndexFileSize	当前媒体文件的已上传字节数 / 总字节数

// 1. 发送前预检，拦截必然失败的场景
File file = selectedFile;
final long FILE_MAX = 1024L * 1024 * 1024;   // 3.2.0 起 1GB；3.2.0 之前为 100MB
if (!file.isFile() || !file.canRead() || file.length() > FILE_MAX) {
    showTip("文件不可访问或超出大小限制");
    return;
}

// 2. 发送并监控进度（大文件务必给进度与取消入口）
ZIMFileMessage message = new ZIMFileMessage(file.getAbsolutePath());
ZIMMessageSendConfig sendConfig = new ZIMMessageSendConfig();
sendConfig.priority = ZIMMessagePriority.HIGH;

zim.sendMessage(message, conversationID, ZIMConversationType.PEER, sendConfig, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageAttached(ZIMMessage message) {
        // 保存此消息对象，供用户在上传中点击取消时使用
        saveSendingMessage(message);
    }

    @Override
    public void onMediaUploadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize) {
        renderProgress(currentFileSize, totalFileSize);
    }

    @Override
    public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 发送成功后获取服务端下载地址
            saveDownloadUrl(((ZIMFileMessage) message).getFileDownloadUrl());
        } else {
            // 业务侧区分错误：参数错误先修正，网络类错误再提供续传或重试入口
            handleSendError(message, errorInfo);
        }
    }
});

// 1. 发送前预检，拦截必然失败的场景
File file = selectedFile;
final long FILE_MAX = 1024L * 1024 * 1024;   // 3.2.0 起 1GB；3.2.0 之前为 100MB
if (!file.isFile() || !file.canRead() || file.length() > FILE_MAX) {
    showTip("文件不可访问或超出大小限制");
    return;
}

// 2. 发送并监控进度（大文件务必给进度与取消入口）
ZIMFileMessage message = new ZIMFileMessage(file.getAbsolutePath());
ZIMMessageSendConfig sendConfig = new ZIMMessageSendConfig();
sendConfig.priority = ZIMMessagePriority.HIGH;

zim.sendMessage(message, conversationID, ZIMConversationType.PEER, sendConfig, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageAttached(ZIMMessage message) {
        // 保存此消息对象，供用户在上传中点击取消时使用
        saveSendingMessage(message);
    }

    @Override
    public void onMediaUploadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize) {
        renderProgress(currentFileSize, totalFileSize);
    }

    @Override
    public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 发送成功后获取服务端下载地址
            saveDownloadUrl(((ZIMFileMessage) message).getFileDownloadUrl());
        } else {
            // 业务侧区分错误：参数错误先修正，网络类错误再提供续传或重试入口
            handleSendError(message, errorInfo);
        }
    }
});

// 1. 发送前预检，拦截必然失败的场景
NSURL *fileURL = selectedFileURL;
unsigned long long fileSize = getFileSize(fileURL); // 业务侧读取文件字节数
if (fileSize > 1024ULL * 1024 * 1024) {   // 3.2.0 起 1GB；3.2.0 之前为 100MB
    showTip(@"文件超出大小限制");
    return;
}

// 2. 发送并监控进度（大文件务必给进度与取消入口）
ZIMFileMessage *fileMsg = [[ZIMFileMessage alloc] init];
// 需填入 UTF-8 格式的本地路径
fileMsg.fileLocalPath = fileURL.path;
// 使用本地上传，不填写网络 URL。
fileMsg.fileDownloadUrl = @"";

ZIMMessageSendConfig *sendConfig = [[ZIMMessageSendConfig alloc] init];
sendConfig.priority = ZIMMessagePriorityHigh;

ZIMMessageSendNotification *notification = [[ZIMMessageSendNotification alloc] init];
notification.onMessageAttached = ^(ZIMMessage * _Nonnull message) {
    saveSendingMessage(message); // 业务侧保存消息对象，供上传期间取消使用
};
notification.onMediaUploadingProgress = ^(ZIMMediaMessage * _Nonnull message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
    renderProgress(currentFileSize, totalFileSize);
};

[[ZIM getInstance] sendMessage:fileMsg toConversationID:conversationID conversationType:ZIMConversationTypePeer config:sendConfig notification:notification callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == 0) {
        // 发送成功后获取服务端下载地址。
        saveDownloadUrl([(ZIMFileMessage *)message fileDownloadUrl]);
    } else {
        handleSendError(message, errorInfo); // 先分类错误，再决定是否重试
    }
}];

// 1. 发送前预检，拦截必然失败的场景
NSURL *fileURL = selectedFileURL;
unsigned long long fileSize = getFileSize(fileURL); // 业务侧读取文件字节数
if (fileSize > 1024ULL * 1024 * 1024) {   // 3.2.0 起 1GB；3.2.0 之前为 100MB
    showTip(@"文件超出大小限制");
    return;
}

// 2. 发送并监控进度（大文件务必给进度与取消入口）
ZIMFileMessage *fileMsg = [[ZIMFileMessage alloc] init];
// 需填入 UTF-8 格式的本地路径
fileMsg.fileLocalPath = fileURL.path;
// 使用本地上传，不填写网络 URL。
fileMsg.fileDownloadUrl = @"";

ZIMMessageSendConfig *sendConfig = [[ZIMMessageSendConfig alloc] init];
sendConfig.priority = ZIMMessagePriorityHigh;

ZIMMessageSendNotification *notification = [[ZIMMessageSendNotification alloc] init];
notification.onMessageAttached = ^(ZIMMessage * _Nonnull message) {
    saveSendingMessage(message); // 业务侧保存消息对象，供上传期间取消使用
};
notification.onMediaUploadingProgress = ^(ZIMMediaMessage * _Nonnull message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
    renderProgress(currentFileSize, totalFileSize);
};

[[ZIM getInstance] sendMessage:fileMsg toConversationID:conversationID conversationType:ZIMConversationTypePeer config:sendConfig notification:notification callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == 0) {
        // 发送成功后获取服务端下载地址。
        saveDownloadUrl([(ZIMFileMessage *)message fileDownloadUrl]);
    } else {
        handleSendError(message, errorInfo); // 先分类错误，再决定是否重试
    }
}];

const file = selectedFile; // 文件选择器返回的 File 对象
const FILE_MAX = 1024 * 1024 * 1024;   // 3.2.0 起 1GB；3.2.0 之前为 100MB

// 1. 发送前预检，拦截必然失败的场景
if (file.size > FILE_MAX) {
  showTip('文件超出大小限制');
  return;
}

const fileMessage: ZIMMessage = {
  type: 12,                  // 12 = 文件消息；14 = 视频消息
  fileLocalPath: file,
};

// 2. 发送并监控进度（大文件务必给进度与取消入口）
let sendingMessage: ZIMMessage; // 保存 SDK 回调中的消息对象
const notification: ZIMMessageSendNotification = {
  onMessageAttached: (message) => { sendingMessage = message; },
  onMediaUploadingProgress: (message, currentFileSize, totalFileSize) => {
    if (totalFileSize > 0) renderProgress(currentFileSize / totalFileSize);
  },
};

zim.sendMessage(fileMessage, conversationID, 0, { priority: 1 }, notification) // 0 = 单聊
  .then((res) => {
    // 发送成功后获取服务端下载地址。
    saveDownloadUrl(res.message.fileDownloadUrl);
  })
  .catch((err: ZIMError) => {
    // 先分类错误：参数错误修正后再发，网络类错误才进入续传或重试流程
    handleSendError(sendingMessage || fileMessage, err);
  });

const file = selectedFile; // 文件选择器返回的 File 对象
const FILE_MAX = 1024 * 1024 * 1024;   // 3.2.0 起 1GB；3.2.0 之前为 100MB

// 1. 发送前预检，拦截必然失败的场景
if (file.size > FILE_MAX) {
  showTip('文件超出大小限制');
  return;
}

const fileMessage: ZIMMessage = {
  type: 12,                  // 12 = 文件消息；14 = 视频消息
  fileLocalPath: file,
};

// 2. 发送并监控进度（大文件务必给进度与取消入口）
let sendingMessage: ZIMMessage; // 保存 SDK 回调中的消息对象
const notification: ZIMMessageSendNotification = {
  onMessageAttached: (message) => { sendingMessage = message; },
  onMediaUploadingProgress: (message, currentFileSize, totalFileSize) => {
    if (totalFileSize > 0) renderProgress(currentFileSize / totalFileSize);
  },
};

zim.sendMessage(fileMessage, conversationID, 0, { priority: 1 }, notification) // 0 = 单聊
  .then((res) => {
    // 发送成功后获取服务端下载地址。
    saveDownloadUrl(res.message.fileDownloadUrl);
  })
  .catch((err: ZIMError) => {
    // 先分类错误：参数错误修正后再发，网络类错误才进入续传或重试流程
    handleSendError(sendingMessage || fileMessage, err);
  });

#include <atomic>
#include <fstream>
#include <memory>
#include <string>

#include "ZIM.h"

namespace {

constexpr unsigned long long kFileMaxBytes = 1024ULL * 1024ULL * 1024ULL;

unsigned long long GetLocalFileSize(const std::string& path) {
    std::ifstream file(path.c_str(), std::ios::binary | std::ios::ate);
    if (!file.is_open()) {
        return 0;
    }
    const auto size = static_cast<std::streamoff>(file.tellg());
    return size > 0 ? static_cast<unsigned long long>(size) : 0;
}

} // namespace

void SendLargeFile(zim::ZIM* zim,
                   const std::string& conversationID,
                   zim::ZIMConversationType conversationType,
                   const std::string& localPath,
                   std::shared_ptr<std::atomic_bool> userClickedCancel) {
    if (!userClickedCancel) {
        return;
    }

    // 1. 发送前预检，拦截必然失败的场景
    const auto fileSize = GetLocalFileSize(localPath);
    if (fileSize == 0) {
        // 文件不存在 / 为空
        return;
    }
    if (fileSize > kFileMaxBytes) {
        // 超过 1GB，直接提示，不发起发送
        return;
    }

    // 2. 构造文件消息
    auto message = std::make_shared<zim::ZIMFileMessage>(localPath);

    zim::ZIMMessageSendConfig sendConfig;
    sendConfig.priority = zim::ZIM_MESSAGE_PRIORITY_HIGH;

    // 调用方为每次发送创建独立的标记，用户点击取消时置为 true。
    // ZIM 实例须在所有发送和取消回调结束前保持有效。
    // cancelRequested 只用于防止进度回调里重复发起取消。
    auto cancelRequested = std::make_shared<std::atomic_bool>(false);

    auto notification = std::make_shared<zim::ZIMMessageSendNotification>();

    notification->onMessageAttached =
        [](std::shared_ptr<zim::ZIMMessage> attachedMessage) {
            (void)attachedMessage;
            // UI：展示“发送中”
        };

    notification->onMediaUploadingProgress =
        [zim, userClickedCancel, cancelRequested](
            std::shared_ptr<zim::ZIMMediaMessage> mediaMessage,
            unsigned long long currentFileSize,
            unsigned long long totalFileSize) {
            (void)currentFileSize;
            (void)totalFileSize;
            // UI：renderProgress(currentFileSize, totalFileSize)

            // 处于文件上传中时，用户点击取消
            if (userClickedCancel->load() && !cancelRequested->exchange(true)) {
                zim->cancelSendingMessage(
                    mediaMessage, zim::ZIMSendingMessageCancelConfig(),
                    [](const zim::ZIMError& errorInfo) {
                        // errorInfo.code == 0：取消指令成功；
                        // 消息状态随后变为发送失败
                    });
            }
        };

    // 组合消息：需要分文件进度时使用
    notification->onMultipleMediaUploadingProgress =
        [](std::shared_ptr<zim::ZIMMultipleMessage> multipleMessage,
           unsigned long long currentFileSize,
           unsigned long long totalFileSize,
           unsigned int messageInfoIndex,
           unsigned long long currentIndexFileSize,
           unsigned long long totalIndexFileSize) {
            (void)multipleMessage;
            (void)currentFileSize;
            (void)totalFileSize;
            (void)messageInfoIndex;
            (void)currentIndexFileSize;
            (void)totalIndexFileSize;
            // messageInfoIndex 用于定位具体失败/上传中的文件
        };

    // 3. 发送并监控结果
    zim->sendMessage(
        message, conversationID, conversationType, sendConfig, notification,
        [](std::shared_ptr<zim::ZIMMessage> sentMessage,
           const zim::ZIMError& errorInfo) {
            if (errorInfo.code == zim::ZIM_ERROR_CODE_SUCCESS) {
                auto fileMessage =
                    std::static_pointer_cast<zim::ZIMFileMessage>(sentMessage);
                if (fileMessage) {
                    // 发送成功：持久化 fileMessage->fileDownloadUrl
                    // saveDownloadUrl(fileMessage->fileDownloadUrl);
                }
                return;
            }

            if (errorInfo.code ==
                zim::ZIM_ERROR_CODE_COMMON_MODULE_PARAMS_INVALID) {
                // 6000001：参数错误（空白消息、发给自己等），不重试
            } else if (errorInfo.code ==
                       zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_SIZE_INVALID) {
                // 6000214：文件大小超限，不重试
            } else if (errorInfo.code ==
                       zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_DURATION_INVALID) {
                // 6000215：音视频时长超限，不重试
            } else if (errorInfo.code ==
                       zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_TYPE_UNSUPPORTED) {
                // 6000213：文件类型/格式不支持，不重试
            } else if (errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_SEND_MESSAGE_FAILED ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_TARGET_DOES_NOT_EXIST ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_SEND_MESSAGE_FAILED_FOR_CANCELLED ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_ERROR ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_NOT_EXIST ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_SERVER_ERROR) {
                // 6000203 / 6000204 / 6000206 / 6000210 / 6000211 / 6000212：
                // 业务、文件或用户取消类错误，按错误码处理，不要等待续传。
            } else if (errorInfo.code ==
                           zim::ZIM_ERROR_CODE_NETWORK_MODULE_NETWORK_ERROR ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_NETWORK_MODULE_REQUEST_TIMEOUT) {
                // 最终回调返回网络错误：保留本地文件，并提供重发入口。
            } else {
                // 其他错误：按错误码处理，不要一律当成网络错误。
            }
        });
}

#include <atomic>
#include <fstream>
#include <memory>
#include <string>

#include "ZIM.h"

namespace {

constexpr unsigned long long kFileMaxBytes = 1024ULL * 1024ULL * 1024ULL;

unsigned long long GetLocalFileSize(const std::string& path) {
    std::ifstream file(path.c_str(), std::ios::binary | std::ios::ate);
    if (!file.is_open()) {
        return 0;
    }
    const auto size = static_cast<std::streamoff>(file.tellg());
    return size > 0 ? static_cast<unsigned long long>(size) : 0;
}

} // namespace

void SendLargeFile(zim::ZIM* zim,
                   const std::string& conversationID,
                   zim::ZIMConversationType conversationType,
                   const std::string& localPath,
                   std::shared_ptr<std::atomic_bool> userClickedCancel) {
    if (!userClickedCancel) {
        return;
    }

    // 1. 发送前预检，拦截必然失败的场景
    const auto fileSize = GetLocalFileSize(localPath);
    if (fileSize == 0) {
        // 文件不存在 / 为空
        return;
    }
    if (fileSize > kFileMaxBytes) {
        // 超过 1GB，直接提示，不发起发送
        return;
    }

    // 2. 构造文件消息
    auto message = std::make_shared<zim::ZIMFileMessage>(localPath);

    zim::ZIMMessageSendConfig sendConfig;
    sendConfig.priority = zim::ZIM_MESSAGE_PRIORITY_HIGH;

    // 调用方为每次发送创建独立的标记，用户点击取消时置为 true。
    // ZIM 实例须在所有发送和取消回调结束前保持有效。
    // cancelRequested 只用于防止进度回调里重复发起取消。
    auto cancelRequested = std::make_shared<std::atomic_bool>(false);

    auto notification = std::make_shared<zim::ZIMMessageSendNotification>();

    notification->onMessageAttached =
        [](std::shared_ptr<zim::ZIMMessage> attachedMessage) {
            (void)attachedMessage;
            // UI：展示“发送中”
        };

    notification->onMediaUploadingProgress =
        [zim, userClickedCancel, cancelRequested](
            std::shared_ptr<zim::ZIMMediaMessage> mediaMessage,
            unsigned long long currentFileSize,
            unsigned long long totalFileSize) {
            (void)currentFileSize;
            (void)totalFileSize;
            // UI：renderProgress(currentFileSize, totalFileSize)

            // 处于文件上传中时，用户点击取消
            if (userClickedCancel->load() && !cancelRequested->exchange(true)) {
                zim->cancelSendingMessage(
                    mediaMessage, zim::ZIMSendingMessageCancelConfig(),
                    [](const zim::ZIMError& errorInfo) {
                        // errorInfo.code == 0：取消指令成功；
                        // 消息状态随后变为发送失败
                    });
            }
        };

    // 组合消息：需要分文件进度时使用
    notification->onMultipleMediaUploadingProgress =
        [](std::shared_ptr<zim::ZIMMultipleMessage> multipleMessage,
           unsigned long long currentFileSize,
           unsigned long long totalFileSize,
           unsigned int messageInfoIndex,
           unsigned long long currentIndexFileSize,
           unsigned long long totalIndexFileSize) {
            (void)multipleMessage;
            (void)currentFileSize;
            (void)totalFileSize;
            (void)messageInfoIndex;
            (void)currentIndexFileSize;
            (void)totalIndexFileSize;
            // messageInfoIndex 用于定位具体失败/上传中的文件
        };

    // 3. 发送并监控结果
    zim->sendMessage(
        message, conversationID, conversationType, sendConfig, notification,
        [](std::shared_ptr<zim::ZIMMessage> sentMessage,
           const zim::ZIMError& errorInfo) {
            if (errorInfo.code == zim::ZIM_ERROR_CODE_SUCCESS) {
                auto fileMessage =
                    std::static_pointer_cast<zim::ZIMFileMessage>(sentMessage);
                if (fileMessage) {
                    // 发送成功：持久化 fileMessage->fileDownloadUrl
                    // saveDownloadUrl(fileMessage->fileDownloadUrl);
                }
                return;
            }

            if (errorInfo.code ==
                zim::ZIM_ERROR_CODE_COMMON_MODULE_PARAMS_INVALID) {
                // 6000001：参数错误（空白消息、发给自己等），不重试
            } else if (errorInfo.code ==
                       zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_SIZE_INVALID) {
                // 6000214：文件大小超限，不重试
            } else if (errorInfo.code ==
                       zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_DURATION_INVALID) {
                // 6000215：音视频时长超限，不重试
            } else if (errorInfo.code ==
                       zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_TYPE_UNSUPPORTED) {
                // 6000213：文件类型/格式不支持，不重试
            } else if (errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_SEND_MESSAGE_FAILED ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_TARGET_DOES_NOT_EXIST ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_SEND_MESSAGE_FAILED_FOR_CANCELLED ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_ERROR ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_NOT_EXIST ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_MESSAGE_MODULE_FILE_SERVER_ERROR) {
                // 6000203 / 6000204 / 6000206 / 6000210 / 6000211 / 6000212：
                // 业务、文件或用户取消类错误，按错误码处理，不要等待续传。
            } else if (errorInfo.code ==
                           zim::ZIM_ERROR_CODE_NETWORK_MODULE_NETWORK_ERROR ||
                       errorInfo.code ==
                           zim::ZIM_ERROR_CODE_NETWORK_MODULE_REQUEST_TIMEOUT) {
                // 最终回调返回网络错误：保留本地文件，并提供重发入口。
            } else {
                // 其他错误：按错误码处理，不要一律当成网络错误。
            }
        });
}

发送视频时，传入视频时长，并替换消息类型及成功回调中的类型转换。

// 在 SendLargeFile 中，把：
// auto message = std::make_shared<zim::ZIMFileMessage>(localPath);
// 换成：
auto message = std::make_shared<zim::ZIMVideoMessage>(localPath, durationSeconds);
// durationSeconds 为视频时长（秒），必须填写。
// 发送成功回调里把 ZIMFileMessage 换成 ZIMVideoMessage 取 fileDownloadUrl。

// 在 SendLargeFile 中，把：
// auto message = std::make_shared<zim::ZIMFileMessage>(localPath);
// 换成：
auto message = std::make_shared<zim::ZIMVideoMessage>(localPath, durationSeconds);
// durationSeconds 为视频时长（秒），必须填写。
// 发送成功回调里把 ZIMFileMessage 换成 ZIMVideoMessage 取 fileDownloadUrl。

import 'dart:io';

import 'package:zego_zim/zego_zim.dart';

const int kFileMaxBytes = 1024 * 1024 * 1024;

/// 业务侧 UI 与进度回调共享的取消标记。
/// 调用方创建并持有该对象；UI 取消按钮设置 userClickedCancel = true。
class UploadCancelToken {
  bool userClickedCancel = false;
  bool cancelRequested = false;
}

Future<void> sendLargeFile(
  String conversationID,
  String localPath,
  UploadCancelToken cancelToken,
) async {
  // 1. 发送前预检
  final file = File(localPath);
  if (!await file.exists()) {
    return;
  }
  final fileSize = await file.length();
  if (fileSize == 0) {
    // 空文件不发起发送
    return;
  }
  if (fileSize > kFileMaxBytes) {
    // 超过 1GB，直接提示
    return;
  }

  final zim = ZIM.getInstance();
  if (zim == null) {
    return;
  }

  // 2. 构造文件消息
  final message = ZIMFileMessage(localPath);

  final sendConfig = ZIMMessageSendConfig()
    ..priority = ZIMMessagePriority.high;

  final notification = ZIMMessageSendNotification(
    onMessageAttached: (ZIMMessage attachedMessage) {
      // UI：展示“发送中”
    },
    onMediaUploadingProgress: (
      ZIMMediaMessage mediaMessage,
      int currentFileSize,
      int totalFileSize,
    ) {
      // UI：renderProgress(currentFileSize, totalFileSize)

      // 处于文件上传中时，用户点击取消
      if (cancelToken.userClickedCancel && !cancelToken.cancelRequested) {
        cancelToken.userClickedCancel = false;
        cancelToken.cancelRequested = true;
        zim
            .cancelSendingMessage(
              mediaMessage,
              ZIMSendingMessageCancelConfig(),
            )
            .then((_) {
              // 取消成功：消息状态会变为发送失败
            })
            .catchError((Object error) {
              // 取消失败时允许用户再次点击取消
              cancelToken.cancelRequested = false;
              if (error is ZIMError && error.code == 6000207) {
                // 当前已经不在上传中
              } else {
                // 其他错误：按错误码处理
              }
            });
      }
    },
    onMultipleMediaUploadingProgress: (
      ZIMMultipleMessage multipleMessage,
      int currentFileSize,
      int totalFileSize,
      int messageInfoIndex,
      int currentIndexFileSize,
      int totalIndexFileSize,
    ) {
      // 组合消息：messageInfoIndex 定位具体文件
    },
  );

  // 3. 发送并监控结果
  try {
    final sentResult = await zim.sendMessage(
      message,
      conversationID,
      ZIMConversationType.peer,
      sendConfig,
      notification,
    );

    final sentMessage = sentResult.message;
    if (sentMessage is ZIMFileMessage) {
      // 发送成功：业务侧持久化 sentMessage.fileDownloadUrl
      // saveDownloadUrl(sentMessage.fileDownloadUrl);
    }
  } catch (e) {
    if (e is ZIMError) {
      if (e.code == 6000001) {
        // 参数错误（空白消息、发给自己等），不重试
      } else if (e.code == 6000214) {
        // 文件大小超限，不重试
      } else if (e.code == 6000215) {
        // 音视频时长超限，不重试
      } else if (e.code == 6000213) {
        // 文件类型/格式不支持，不重试
      } else {
        // 其他错误：按错误码处理，不要一律当成网络错误。
      }
    } else {
      rethrow;
    }
  }
}

import 'dart:io';

import 'package:zego_zim/zego_zim.dart';

const int kFileMaxBytes = 1024 * 1024 * 1024;

/// 业务侧 UI 与进度回调共享的取消标记。
/// 调用方创建并持有该对象；UI 取消按钮设置 userClickedCancel = true。
class UploadCancelToken {
  bool userClickedCancel = false;
  bool cancelRequested = false;
}

Future<void> sendLargeFile(
  String conversationID,
  String localPath,
  UploadCancelToken cancelToken,
) async {
  // 1. 发送前预检
  final file = File(localPath);
  if (!await file.exists()) {
    return;
  }
  final fileSize = await file.length();
  if (fileSize == 0) {
    // 空文件不发起发送
    return;
  }
  if (fileSize > kFileMaxBytes) {
    // 超过 1GB，直接提示
    return;
  }

  final zim = ZIM.getInstance();
  if (zim == null) {
    return;
  }

  // 2. 构造文件消息
  final message = ZIMFileMessage(localPath);

  final sendConfig = ZIMMessageSendConfig()
    ..priority = ZIMMessagePriority.high;

  final notification = ZIMMessageSendNotification(
    onMessageAttached: (ZIMMessage attachedMessage) {
      // UI：展示“发送中”
    },
    onMediaUploadingProgress: (
      ZIMMediaMessage mediaMessage,
      int currentFileSize,
      int totalFileSize,
    ) {
      // UI：renderProgress(currentFileSize, totalFileSize)

      // 处于文件上传中时，用户点击取消
      if (cancelToken.userClickedCancel && !cancelToken.cancelRequested) {
        cancelToken.userClickedCancel = false;
        cancelToken.cancelRequested = true;
        zim
            .cancelSendingMessage(
              mediaMessage,
              ZIMSendingMessageCancelConfig(),
            )
            .then((_) {
              // 取消成功：消息状态会变为发送失败
            })
            .catchError((Object error) {
              // 取消失败时允许用户再次点击取消
              cancelToken.cancelRequested = false;
              if (error is ZIMError && error.code == 6000207) {
                // 当前已经不在上传中
              } else {
                // 其他错误：按错误码处理
              }
            });
      }
    },
    onMultipleMediaUploadingProgress: (
      ZIMMultipleMessage multipleMessage,
      int currentFileSize,
      int totalFileSize,
      int messageInfoIndex,
      int currentIndexFileSize,
      int totalIndexFileSize,
    ) {
      // 组合消息：messageInfoIndex 定位具体文件
    },
  );

  // 3. 发送并监控结果
  try {
    final sentResult = await zim.sendMessage(
      message,
      conversationID,
      ZIMConversationType.peer,
      sendConfig,
      notification,
    );

    final sentMessage = sentResult.message;
    if (sentMessage is ZIMFileMessage) {
      // 发送成功：业务侧持久化 sentMessage.fileDownloadUrl
      // saveDownloadUrl(sentMessage.fileDownloadUrl);
    }
  } catch (e) {
    if (e is ZIMError) {
      if (e.code == 6000001) {
        // 参数错误（空白消息、发给自己等），不重试
      } else if (e.code == 6000214) {
        // 文件大小超限，不重试
      } else if (e.code == 6000215) {
        // 音视频时长超限，不重试
      } else if (e.code == 6000213) {
        // 文件类型/格式不支持，不重试
      } else {
        // 其他错误：按错误码处理，不要一律当成网络错误。
      }
    } else {
      rethrow;
    }
  }
}

发送视频时，传入视频时长，并替换消息类型及成功回调中的类型转换。

// 在 sendLargeFile 中，把：
// final message = ZIMFileMessage(localPath);
// 换成：
final message = ZIMVideoMessage(
  localPath,
  videoDuration: durationSeconds,
);
// durationSeconds 为视频时长（秒），必须填写。
// 发送成功回调里把 ZIMFileMessage 换成 ZIMVideoMessage 取 fileDownloadUrl。

// 在 sendLargeFile 中，把：
// final message = ZIMFileMessage(localPath);
// 换成：
final message = ZIMVideoMessage(
  localPath,
  videoDuration: durationSeconds,
);
// durationSeconds 为视频时长（秒），必须填写。
// 发送成功回调里把 ZIMFileMessage 换成 ZIMVideoMessage 取 fileDownloadUrl。

// sendingMessage 为当前仍在上传的消息对象。
zim.cancelSendingMessage(sendingMessage, new ZIMSendingMessageCancelConfig(),
    new ZIMSendingMessageCancelledCallback() {
        @Override
        public void onSendingMessageCancelled(ZIMError errorInfo) {
            // 根据取消结果更新 UI；确认放弃后再清理本地文件。
        }
    });

// sendingMessage 为当前仍在上传的消息对象。
zim.cancelSendingMessage(sendingMessage, new ZIMSendingMessageCancelConfig(),
    new ZIMSendingMessageCancelledCallback() {
        @Override
        public void onSendingMessageCancelled(ZIMError errorInfo) {
            // 根据取消结果更新 UI；确认放弃后再清理本地文件。
        }
    });

ZIMSendingMessageCancelConfig *config = [[ZIMSendingMessageCancelConfig alloc] init];
[zim cancelSendingMessage:sendingMessage config:config callback:^(ZIMError *errorInfo) {
    // 根据取消结果更新 UI；确认放弃后再清理本地文件。
}];

ZIMSendingMessageCancelConfig *config = [[ZIMSendingMessageCancelConfig alloc] init];
[zim cancelSendingMessage:sendingMessage config:config callback:^(ZIMError *errorInfo) {
    // 根据取消结果更新 UI；确认放弃后再清理本地文件。
}];

// sendingMessage 为 onMessageAttached 或上传进度回调中保存的消息对象。
zim.cancelSendingMessage(sendingMessage, {} as ZIMSendingMessageCancelConfig)
  .then(() => { /* 更新取消状态；确认放弃后再清理本地文件 */ })
  .catch((err: ZIMError) => { /* 展示取消失败原因 */ });

// sendingMessage 为 onMessageAttached 或上传进度回调中保存的消息对象。
zim.cancelSendingMessage(sendingMessage, {} as ZIMSendingMessageCancelConfig)
  .then(() => { /* 更新取消状态；确认放弃后再清理本地文件 */ })
  .catch((err: ZIMError) => { /* 展示取消失败原因 */ });

void CancelMediaSending(zim::ZIM* zim,
                        std::shared_ptr<zim::ZIMMessage> message) {
    zim->cancelSendingMessage(
        message, zim::ZIMSendingMessageCancelConfig(),
        [](const zim::ZIMError& errorInfo) {
            (void)errorInfo;
            if (errorInfo.code == zim::ZIM_ERROR_CODE_SUCCESS) {
                // 取消成功：消息状态会变为发送失败
            } else if (errorInfo.code ==
                       zim::ZIM_ERROR_CODE_MESSAGE_MODULE_CANCEL_SENDING_MESSAGE_FAILED) {
                // 6000207：当前已经不在上传中，或任务已结束
            }
        });
}

void CancelMediaSending(zim::ZIM* zim,
                        std::shared_ptr<zim::ZIMMessage> message) {
    zim->cancelSendingMessage(
        message, zim::ZIMSendingMessageCancelConfig(),
        [](const zim::ZIMError& errorInfo) {
            (void)errorInfo;
            if (errorInfo.code == zim::ZIM_ERROR_CODE_SUCCESS) {
                // 取消成功：消息状态会变为发送失败
            } else if (errorInfo.code ==
                       zim::ZIM_ERROR_CODE_MESSAGE_MODULE_CANCEL_SENDING_MESSAGE_FAILED) {
                // 6000207：当前已经不在上传中，或任务已结束
            }
        });
}

Future<void> cancelMediaSending(ZIMMessage message) async {
  final zim = ZIM.getInstance();
  if (zim == null) {
    return;
  }

  try {
    await zim.cancelSendingMessage(
      message,
      ZIMSendingMessageCancelConfig(),
    );
    // 取消成功：消息状态会变为发送失败
  } catch (e) {
    if (e is ZIMError && e.code == 6000207) {
      // 当前已经不在上传中
    }
  }
}

Future<void> cancelMediaSending(ZIMMessage message) async {
  final zim = ZIM.getInstance();
  if (zim == null) {
    return;
  }

  try {
    await zim.cancelSendingMessage(
      message,
      ZIMSendingMessageCancelConfig(),
    );
    // 取消成功：消息状态会变为发送失败
  } catch (e) {
    if (e is ZIMError && e.code == 6000207) {
      // 当前已经不在上传中
    }
  }
}

ZIMMediaDownloadConfig config = new ZIMMediaDownloadConfig();
zim.downloadMediaFile(message, ZIMMediaFileType.ORIGINAL_FILE, config,
    new ZIMMediaDownloadedCallback() {
        @Override
        public void onMediaDownloadingProgress(ZIMMessage message, long currentFileSize,
            long totalFileSize) {
            // 更新下载进度。
        }

        @Override
        public void onMediaDownloaded(ZIMMessage message, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                String localPath = ((ZIMMediaMessage) message).getFileLocalPath();
                // 使用本地文件。
            } else {
                // 展示下载失败原因，并提供重试入口。
            }
        }
    });

ZIMMediaDownloadConfig config = new ZIMMediaDownloadConfig();
zim.downloadMediaFile(message, ZIMMediaFileType.ORIGINAL_FILE, config,
    new ZIMMediaDownloadedCallback() {
        @Override
        public void onMediaDownloadingProgress(ZIMMessage message, long currentFileSize,
            long totalFileSize) {
            // 更新下载进度。
        }

        @Override
        public void onMediaDownloaded(ZIMMessage message, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                String localPath = ((ZIMMediaMessage) message).getFileLocalPath();
                // 使用本地文件。
            } else {
                // 展示下载失败原因，并提供重试入口。
            }
        }
    });

ZIMMediaDownloadConfig *config = [[ZIMMediaDownloadConfig alloc] init];
[zim downloadMediaFileWithMessage:(ZIMMediaMessage *)message
                        fileType:ZIMMediaFileTypeOriginalFile
                          config:config
                        progress:^(ZIMMessage *message, unsigned long long currentFileSize,
                                   unsigned long long totalFileSize) {
    // 更新下载进度。
} callback:^(ZIMMessage *message, ZIMError *errorInfo) {
    if (errorInfo.code == 0) {
        NSString *localPath = ((ZIMMediaMessage *)message).fileLocalPath;
        // 使用本地文件。
    } else {
        // 展示下载失败原因，并提供重试入口。
    }
}];

ZIMMediaDownloadConfig *config = [[ZIMMediaDownloadConfig alloc] init];
[zim downloadMediaFileWithMessage:(ZIMMediaMessage *)message
                        fileType:ZIMMediaFileTypeOriginalFile
                          config:config
                        progress:^(ZIMMessage *message, unsigned long long currentFileSize,
                                   unsigned long long totalFileSize) {
    // 更新下载进度。
} callback:^(ZIMMessage *message, ZIMError *errorInfo) {
    if (errorInfo.code == 0) {
        NSString *localPath = ((ZIMMediaMessage *)message).fileLocalPath;
        // 使用本地文件。
    } else {
        // 展示下载失败原因，并提供重试入口。
    }
}];

// message 为文件或视频消息，业务侧按需展示下载链接。
renderDownloadLink(message.fileDownloadUrl);

// message 为文件或视频消息，业务侧按需展示下载链接。
renderDownloadLink(message.fileDownloadUrl);

// 用户点击下载后调用。message 为选中的文件或视频消息。
void DownloadOriginalFile(zim::ZIM* zim,
                          const std::shared_ptr<zim::ZIMMessage>& message) {
    zim::ZIMMediaDownloadConfig config;
    // 组合消息内下载时，用 config.messageInfoIndex 指定子文件下标

    zim->downloadMediaFile(
        message, zim::ZIM_MEDIA_FILE_TYPE_ORIGINAL_FILE, config,
        [](std::shared_ptr<zim::ZIMMessage> /*message*/,
           unsigned long long currentFileSize,
           unsigned long long totalFileSize) {
            (void)currentFileSize;
            (void)totalFileSize;
            // UI：下载进度
        },
        [](std::shared_ptr<zim::ZIMMessage> downloadedMessage,
           const zim::ZIMError& errorInfo) {
            if (errorInfo.code != zim::ZIM_ERROR_CODE_SUCCESS) {
                return;
            }

            auto mediaMessage =
                std::static_pointer_cast<zim::ZIMMediaMessage>(
                    downloadedMessage);
            (void)mediaMessage;
            // 下载成功后，本地路径在 mediaMessage->fileLocalPath
            // play(mediaMessage->fileLocalPath);
        });
}

// 用户点击下载后调用。message 为选中的文件或视频消息。
void DownloadOriginalFile(zim::ZIM* zim,
                          const std::shared_ptr<zim::ZIMMessage>& message) {
    zim::ZIMMediaDownloadConfig config;
    // 组合消息内下载时，用 config.messageInfoIndex 指定子文件下标

    zim->downloadMediaFile(
        message, zim::ZIM_MEDIA_FILE_TYPE_ORIGINAL_FILE, config,
        [](std::shared_ptr<zim::ZIMMessage> /*message*/,
           unsigned long long currentFileSize,
           unsigned long long totalFileSize) {
            (void)currentFileSize;
            (void)totalFileSize;
            // UI：下载进度
        },
        [](std::shared_ptr<zim::ZIMMessage> downloadedMessage,
           const zim::ZIMError& errorInfo) {
            if (errorInfo.code != zim::ZIM_ERROR_CODE_SUCCESS) {
                return;
            }

            auto mediaMessage =
                std::static_pointer_cast<zim::ZIMMediaMessage>(
                    downloadedMessage);
            (void)mediaMessage;
            // 下载成功后，本地路径在 mediaMessage->fileLocalPath
            // play(mediaMessage->fileLocalPath);
        });
}

// 用户点击下载后调用。message 为选中的文件或视频消息。
Future<void> downloadOriginalFile(ZIM zim, ZIMMessage message) async {
  try {
    final downloaded = await zim.downloadMediaFile(
      message,
      ZIMMediaFileType.originalFile,
      ZIMMediaDownloadConfig(),
      (
        ZIMMessage msg,
        int currentFileSize,
        int totalFileSize,
      ) {
        // UI：下载进度
      },
    );

    final mediaMessage = downloaded.message as ZIMMediaMessage;
    // 下载成功后，本地路径在 mediaMessage.fileLocalPath（API 类型为 dynamic）
    final localPath = mediaMessage.fileLocalPath;
    if (localPath is String) {
      // play(localPath);
    }
  } catch (_) {
    // 处理下载失败
  }
}

// 用户点击下载后调用。message 为选中的文件或视频消息。
Future<void> downloadOriginalFile(ZIM zim, ZIMMessage message) async {
  try {
    final downloaded = await zim.downloadMediaFile(
      message,
      ZIMMediaFileType.originalFile,
      ZIMMediaDownloadConfig(),
      (
        ZIMMessage msg,
        int currentFileSize,
        int totalFileSize,
      ) {
        // UI：下载进度
      },
    );

    final mediaMessage = downloaded.message as ZIMMediaMessage;
    // 下载成功后，本地路径在 mediaMessage.fileLocalPath（API 类型为 dynamic）
    final localPath = mediaMessage.fileLocalPath;
    if (localPath is String) {
      // play(localPath);
    }
  } catch (_) {
    // 处理下载失败
  }
}

大文件上传与断点续传

功能简介

前提条件与适用范围

实现方案

选择文件发送方式

上传进度与发送结果

中断恢复与断点续传

取消上传

接收端下载与本地文件兜底

实现大文件上传

发送文件并监听进度

按用户操作取消上传

按需下载原文件

接入最佳实践

常见问题