logo
On this page

ZIM upgrade Guide


This article provides some instructions and considerations for upgrading the ZIM SDK for Windows version.

2.19.0 upgrade guide

Warning

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.

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.

Usage in Version 2.19.0(For Multi-item Messages)
Usage in Version 2.19.0(For other Messages)
Old Usage
// 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
                                         ......
                                     });
1
Copied!
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
                                         ......
                                     });
1
Copied!
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
                                     });;
1
Copied!

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.

Usage in Version 2.19.0
Old Usage
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
                               });
1
Copied!
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
                                     });
1
Copied!

2.18.0 upgrade guide

Warning

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).
Untitled
// 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*/) {}
1
Copied!

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.
Untitled
// 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*/) {}
1
Copied!

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.
Untitled
// 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*/) {}
1
Copied!

2.16.0 Upgrade Guide

Warning

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

Note

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.

Usage in version 2.16.0
Usage in old versions
// 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) {
});
1
Copied!
// 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) {
});
1
Copied!

Previous

ZIM release notes

Next

Authentication