ZIM 升级指南
本文介绍 ZIM Android 平台 SDK 版本升级时的一些说明和注意事项。
2.19.0 升级指南
从 2.19.0 版本开始,以下接口有重大变更,因此在从旧版本升级到 2.19.0 版本时,请您阅读以下指南。
downloadMediaFile 及相关回调
废弃原接口 downloadMediaFile
,请使用同名 downloadMediaFile 代替。新版本的 downloadMediaFile 新增了 config
参数,新增了 config
参数,可用于指定下载组合消息中的单个媒体内容。
ZIMMediaDownloadingProgress 以及 ZIMMediaDownloadedCallback 中,参数 message
的类型从 const std::shared_ptr<ZIMMediaMessage> &
变更为 const std::shared_ptr<ZIMMessage> &
,以适应组合消息使用,开发者需要根据 IDE 的编译错误提示修正调用。
// 假设 multipleMessage.messageInfoList[0] 是文本消息,multipleMessage.messageInfoList[1] 是图片消息
auto multipleMessage = std::static_pointer_cast<ZIMMultipleMessage>(message);
ZIMMediaDownloadConfig config;
// 指定下载图片消息
config.messageInfoIndex = 1;
ZIM::getInstance()->downloadMediaFile(multipleMessage,
ZIMMediaFileType::ZIM_MEDIA_FILE_TYPE_ORIGINAL_FILE,
config,
[=](const std::shared_ptr<ZIMMessage> &message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
// 下载进度
// 开发者需要判断 message 的类型并转换成对应类型的消息
if (message->getType() == ZIMMessageType::ZIM_MESSAGE_TYPE_MULTIPLE) {
auto multipleMessage = std::static_pointer_cast<ZIMMultipleMessage>(message);
// 处理组合消息
}
// 其他类型消息的处理
......
},
[=](const std::shared_ptr<ZIMMessage> &message, const ZIMError &errorInfo) {
// 下载完成
// 开发者需要判断 message 的类型并转换成对应类型的消息
if (message->getType() == ZIMMessageType::ZIM_MESSAGE_TYPE_MULTIPLE) {
auto multipleMessage = std::static_pointer_cast<ZIMMultipleMessage>(message);
// 处理组合消息
}
// 其他类型消息的处理
......
});
auto imageMessage = std::static_pointer_cast<ZIMImageMessage>(message);
ZIMMediaDownloadConfig config;
ZIM::getInstance()->downloadMediaFile(imageMessage,
ZIMMediaFileType::ZIM_MEDIA_FILE_TYPE_ORIGINAL_FILE,
config,
[=](const std::shared_ptr<ZIMMessage> &message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
// 下载进度
// 开发者需要判断 message 的类型并转换成对应类型的消息
if (message->getType() == ZIMMessageType::ZIM_MESSAGE_TYPE_IMAGE) {
auto imageMessage = std::static_pointer_cast<ZIMImageMessage>(message);
// 处理图片消息
}
// 其他类型消息的处理
......
},
[=](const std::shared_ptr<ZIMMessage> &message, const ZIMError &errorInfo) {
// 下载完成
// 开发者需要判断 message 的类型并转换成对应类型的消息
if (message->getType() == ZIMMessageType::ZIM_MESSAGE_TYPE_IMAGE) {
auto imageMessage = std::static_pointer_cast<ZIMImageMessage>(message);
// 处理图片消息
}
// 其他类型消息的处理
......
});
auto imageMessage = std::static_pointer_cast<ZIMImageMessage>(message);
ZIM::getInstance()->downloadMediaFile(imageMessage,
ZIMMediaFileType::ZIM_MEDIA_FILE_TYPE_ORIGINAL_FILE,
[=](const std::shared_ptr<ZIMMediaMessage> &message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
// 下载进度
},
[=](const std::shared_ptr<ZIMMediaMessage> &message, const ZIMError &errorInfo) {
// 下载完成
});;
sendMessage
sendMediaMessage
自 2.19.0 版本后,发送多媒体消息需使用 sendMessage 接口。sendMediaMessage
接口被废弃,以实现发送消息的统一性和便于后续的通用扩展。
auto imageMessage = std::static_pointer_cast<ZIMImageMessage>(message);
ZIMMessageSendConfig config;
config.priority = ZIMMessagePriority::ZIM_MESSAGE_PRIORITY_MEDIUM;
auto notification = std::make_shared<ZIMMessageSendNotification>();
notification->onMessageAttached = [=](const std::shared_ptr<ZIMMessage> &message) {
// 开发者可以监听这个回调执行消息发送前的业务逻辑
};
notification->onMediaUploadingProgress = [=](const std::shared_ptr<ZIMMediaMessage> &message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
// 多媒体上传进度
};
ZIM::getInstance()->sendMessage(imageMessage,
"TO_CONVERSATION_ID",
ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER,
config,
notification,
[=](const std::shared_ptr<ZIMMessage> &message, const ZIMError &errorInfo) {
// 消息发送结果
});
auto imageMessage = std::static_pointer_cast<ZIMImageMessage>(message);
ZIMMessageSendConfig config;
config.priority = ZIMMessagePriority::ZIM_MESSAGE_PRIORITY_MEDIUM;
auto notification = std::make_shared<ZIMMediaMessageSendNotification>();
notification->onMessageAttached = [=](const std::shared_ptr<ZIMMessage> &message) {
// 开发者可以监听这个回调执行消息发送前的业务逻辑
};
notification->onMediaUploadingProgress = [=](const std::shared_ptr<ZIMMediaMessage> &message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
// 多媒体上传进度
};
ZIM::getInstance()->sendMediaMessage(imageMessage,
"TO_CONVERSATION_ID",
ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER,
config,
notification,
[=](const std::shared_ptr<ZIMMessage> &message, const ZIMError &errorInfo) {
// 消息发送结果
});
2.18.0 升级指南
从 2.18.0 版本开始,以下接口有重大变更,因此在从旧版本升级到 2.18.0 版本时,请您阅读以下指南。
单聊消息接收回调
原单聊消息接收回调 onReceivePeerMessage
已被废弃,请使用 onPeerMessageReceived 代替。
新回调支持以下功能:
- 用户在线时,可通过此回调接收在线单聊消息。
- 用户重新登录 ZIM SDK 后,可以通过此回调接收离线期间(最长7天)收到的所有单聊消息。
//新接口
virtual void
onPeerMessageReceived(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const ZIMMessageReceivedInfo & /*info*/,
const std::string & /*fromUserID*/) {}
//老接口
virtual void
onReceivePeerMessage(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const std::string & /*fromUserID*/) {}
房间消息接收回调
原房间消息接收回调 onReceiveRoomMessage
已被废弃,请使用 onRoomMessageReceived 代替。
新回调支持以下功能:
- 用户在线时,可通过此回调接收在线房间消息。
- 用户从离线恢复到在线后,若仍在房间中,即可通过此回调接收离线期间内的所有房间消息。
//新接口
virtual void
onRoomMessageReceived(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const ZIMMessageReceivedInfo & /*info*/,
const std::string & /*fromRoomID*/) {}
//老接口
virtual void
onReceiveRoomMessage(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const std::string & /*fromRoomID*/) {}
群组消息接收回调
原群组消息接收回调 onReceiveGroupMessage
已被废弃,请使用 onGroupMessageReceived 代替。
新回调支持以下功能:
- 用户在线时,可通过此回调接收在线群组消息。
- 用户重新登录 ZIM SDK 后,可以通过通过此回调接收离线期间(最长7天)收到的所有群聊消息。
//新接口
virtual void onGroupMessageReceived(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const ZIMMessageReceivedInfo & /*info*/,
const std::string & /*fromGroupID*/) {}
//老接口
virtual void onReceiveGroupMessage(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const std::string & /*fromGroupID*/) {}
2.16.0 升级指南
从 2.16.0 版本开始,以下接口有重大变更,因此在从旧版本升级到 2.16.0 版本时,请您阅读以下指南。
callCancel
以下变更仅对进阶模式呼叫邀请而言。
在新版本的 callCancel 中,如果参数 userIDs 包含一个 userID,则该接口将仅取消邀请该被叫用户。如果 userIDs 参数为空,则该接口将对所有被叫用户取消邀请。
而对于旧版本的 callCancel
接口,无论参数 userIDs 是否为空,均视为对所有被叫用户取消邀请。
由于旧版 ZIM SDK 不兼容单独取消逻辑,因此如果您既需要保留使用老版本 ZIM 实现的取消逻辑,又需要使用新版本的单独取消功能,请隔离新老版本 ZIM 之间的呼叫功能。
// 单独取消 userIdA 、userIdB
std::vector<std::string> invitees;
invitees.emplace_back("userIdA");
invitees.emplace_back("userIdB");
ZIMCallCancelConfig config;
zim->callCancel(invitees, "callID", config, [=](const std::string& callID, const std::vector<std::string>& errorInvitees,
const ZIMError& errorInfo) {
});
// 取消整个呼叫邀请,当整个呼叫中所有被叫都未接受时可以调用成功
std::vector<std::string> invitees;
ZIMCallCancelConfig config;
zim->callCancel(invitees, "callID", config, [=](const std::string& callID, const std::vector<std::string>& errorInvitees,
const ZIMError& errorInfo) {
});
// 无论 userIDs 中是否传递 userID,均为取消整个呼叫,当整个呼叫中所有被叫都未接受时可以调用成功
std::vector<std::string> invitees;
invitees.emplace_back("userIdA");
invitees.emplace_back("userIdB");
ZIMCallCancelConfig config;
zim->callCancel(invitees, "callID", config, [=](const std::string& callID, const std::vector<std::string>& errorInvitees,
const ZIMError& errorInfo) {
});
// 取消整个呼叫邀请,当整个呼叫中所有被叫都未接受时可以调用成功
std::vector<std::string> invitees;
ZIMCallCancelConfig config;
zim->callCancel(invitees, "callID", config, [=](const std::string& callID, const std::vector<std::string>& errorInvitees,
const ZIMError& errorInfo) {
});