ZIM upgrade Guide
This article provides some instructions and considerations for upgrading the ZIM SDK for Windows version.
2.19.0 upgrade guide
Starting from version 2.19.0, the following interfaces have undergone significant changes. Therefore, when upgrading from an older version to version 2.19.0, please read the following guidelines.
downloadMediaFile and related callbacks
The original downloadMediaFile
API is deprecated. Please use the new downloadMediaFile instead. The updated downloadMediaFile introduces a new config
parameter, which can be used to specify the download of individual media content in multi-item messages.
In ZIMMediaDownloadingProgress and ZIMMediaDownloadedCallback, the message
parameter type has changed from const std::shared_ptr<ZIMMediaMessage> &
to const std::shared_ptr<ZIMMessage> &
to support multi-item messages. Developers need to fix the calls according to the IDE's compile error hints.
// Assume multipleMessage.messageInfoList[0] is a text message, and multipleMessage.messageInfoList[1] is an image message
auto multipleMessage = std::static_pointer_cast<ZIMMultipleMessage>(message);
ZIMMediaDownloadConfig config;
// Specify to download the image message
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) {
// Download Progress
// Developers need to check the type of the message and cast it to the corresponding message type
if (message->getType() == ZIMMessageType::ZIM_MESSAGE_TYPE_MULTIPLE) {
auto multipleMessage = std::static_pointer_cast<ZIMMultipleMessage>(message);
// Handle multi-item messages
}
// Handle other message types
......
},
[=](const std::shared_ptr<ZIMMessage> &message, const ZIMError &errorInfo) {
// Download completed
// Developers need to check the type of the message and cast it to the corresponding message type
if (message->getType() == ZIMMessageType::ZIM_MESSAGE_TYPE_MULTIPLE) {
auto multipleMessage = std::static_pointer_cast<ZIMMultipleMessage>(message);
// Handle multi-item messages
}
// Handle other message types
......
});
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) {
// Download Progress
// Developers need to check the type of the message and cast it to the corresponding message type
if (message->getType() == ZIMMessageType::ZIM_MESSAGE_TYPE_IMAGE) {
auto imageMessage = std::static_pointer_cast<ZIMImageMessage>(message);
// Handle image messages
}
// Handle other message types
......
},
[=](const std::shared_ptr<ZIMMessage> &message, const ZIMError &errorInfo) {
// Download completed
// Developers need to check the type of the message and cast it to the corresponding message type
if (message->getType() == ZIMMessageType::ZIM_MESSAGE_TYPE_IMAGE) {
auto imageMessage = std::static_pointer_cast<ZIMImageMessage>(message);
// Handle image messages
}
// Handle other message types
......
});
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) {
// Download Progress
},
[=](const std::shared_ptr<ZIMMediaMessage> &message, const ZIMError &errorInfo) {
// Download completed
});;
sendMessage
sendMediaMessage
Since version 2.19.0, multimedia messages must be sent using the sendMessage interface. The sendMediaMessage
interface is deprecated to unify message sending and facilitate future general extensions.
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) {
// Developers can listen to this callback to execute business logic before sending the message
};
notification->onMediaUploadingProgress = [=](const std::shared_ptr<ZIMMediaMessage> &message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
// Upload Progress
};
ZIM::getInstance()->sendMessage(imageMessage,
"TO_CONVERSATION_ID",
ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER,
config,
notification,
[=](const std::shared_ptr<ZIMMessage> &message, const ZIMError &errorInfo) {
// Message Send Result
});
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) {
// Developers can listen to this callback to execute business logic before sending the message
};
notification->onMediaUploadingProgress = [=](const std::shared_ptr<ZIMMediaMessage> &message, unsigned long long currentFileSize, unsigned long long totalFileSize) {
// Upload Progress
};
ZIM::getInstance()->sendMediaMessage(imageMessage,
"TO_CONVERSATION_ID",
ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER,
config,
notification,
[=](const std::shared_ptr<ZIMMessage> &message, const ZIMError &errorInfo) {
// Message Send Result
});
2.18.0 upgrade guide
Starting from version 2.18.0, the following interfaces have undergone significant changes. Therefore, when upgrading from an older version to version 2.18.0, please read the following guidelines.
Callback on receiving one-to-one messages
The deprecated callback onReceivePeerMessage
for receiving one-to-one messages has been replaced by onPeerMessageReceived.
The new callback supports the following features:
- When a user is online, they can receive one-to-one messages through this callback.
- When a user logs back into the ZIM SDK, they can receive all one-to-one messages received during their offline period (up to 7 days).
// New callback
virtual void
onPeerMessageReceived(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const ZIMMessageReceivedInfo & /*info*/,
const std::string & /*fromUserID*/) {}
// Old callback
virtual void
onReceivePeerMessage(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const std::string & /*fromUserID*/) {}
Callback on receiving room messages
The deprecated callback onReceiveRoomMessage
for receiving room messages has been replaced by onRoomMessageReceived.
The new callback supports the following features:
- When a user is online, they can receive online room messages through this callback.
- When a user goes from offline to online and is still in the room, they can receive all room messages that were sent during their offline period through this callback.
// New callback
virtual void
onRoomMessageReceived(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const ZIMMessageReceivedInfo & /*info*/,
const std::string & /*fromRoomID*/) {}
// Old callback
virtual void
onReceiveRoomMessage(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const std::string & /*fromRoomID*/) {}
Callback on receiving group messages
The deprecated callback onReceiveGroupMessage
for receiving group messages has been replaced by onGroupMessageReceived.
The new callback supports the following features:
- When the user is online, they can receive online group messages through this callback.
- When the user logs back into the ZIM SDK, they can receive all group chat messages received during the offline period (up to 7 days) through this callback.
// New callback
virtual void onGroupMessageReceived(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const ZIMMessageReceivedInfo & /*info*/,
const std::string & /*fromGroupID*/) {}
// New callback
virtual void onReceiveGroupMessage(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const std::string & /*fromGroupID*/) {}
2.16.0 Upgrade Guide
Starting from version 2.16.0, there are significant changes to the following interfaces. Therefore, when upgrading from an older version to version 2.16.0, please read the following guide.
callCancel
The following changes only apply to advanced mode call invitations.
In the new version of callCancel, if the parameter userIDs contains a userID, this interface will only cancel the invitation for that callee. If the userIDs parameter is empty, this interface will cancel the invitation for all callees.
For the old version of the callCancel
interface, regardless of whether the userIDs parameter is empty or not, it is considered as canceling the invitation for all callees.
Since the old version of the ZIM SDK is not compatible with separate cancellation logic, if you need to retain the cancellation logic implemented using the old version of ZIM and also need to use the separate cancellation feature of the new version, please isolate the call functionality between the old and new versions of ZIM.
// Cancel userIdA and userIdB separately
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) {
});
// Cancel the entire call invitation, can be called successfully when none of the callees in the call have accepted
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) {
});
// Regardless of whether the userID is passed in the userIDs, it is considered as canceling the entire call, can be called successfully when none of the callees in the call have accepted
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) {
});
// Cancel the entire call invitation, can be called successfully when none of the callees in the call have accepted
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) {
});