This document describes the usage of some basic features of the Tencent Cloud IM SDK to give you a better understanding of the basic processes of Instant Messaging (IM).
Before using the SDK to perform IM operations, you need to initialize the SDK.
Example:
int sdk_app_id = 12345678;
std::string json_init_cfg;
Json::Value json_value_dev;
json_value_dev[kTIMDeviceInfoDevId] = "12345678";
json_value_dev[kTIMDeviceInfoPlatform] = TIMPlatform::kTIMPlatform_Windows;
json_value_dev[kTIMDeviceInfoDevType] = "";
Json::Value json_value_init;
json_value_init[kTIMSdkConfigLogFilePath] = path;
json_value_init[kTIMSdkConfigConfigFilePath] = path;
json_value_init[kTIMSdkConfigAccountType] = "107";
json_value_init[kTIMSdkConfigDeviceInfo] = json_value_dev;
TIMInit(sdk_app_id, json_value_init.toStyledString().c_str());
You can obtain the SDKAppID after creating an app in the IM console. For more information on initialization operations, see Initialization.
Example:
const void* user_data = nullptr; // Return of the callback function
const char* id = "WIN01";
const char* user_sig = "WIN01UserSig";
TIMLogin(id, user_sig, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
if (code != ERR_SUCC) {
// Failed to log in
return;
}
// Logged in successfully
}, user_data);
Here, code indicates the error code and desc indicates error description. For more information, see Error Codes.
onForceOffline
If this user has been forced logout by another client, the login fails and returns the error code (ERR_IMSDK_KICKED_BY_OTHERS: 6208
). If a user is forced logout, be sure to notify the user of this with a notification window such as an Alert window. For more information on forcible logout, see User State Changes.
onUserSigExpired
Every UserSig has an expiration time. When a UserSig expires, login
returns error code 70001
. If you receive this error code, request a new UserSig from your business server. For more information, see User Ticket Expiration.
The logout operation needs to be called if the user wants to log out or switch to another user.
Example:
const void* user_data = nullptr; // Return of the callback function
TIMLogout([](int32_t code, const char* desc, const char* json_param, const void* user_data) {
if (code != ERR_SUCC) {
// Failed to log out
return;
}
// Logged out successfully
}, user_data);
When you need to switch to another account,
login
can be called again only after thelogout
callback succeeds or fails. Otherwise,login
may fail.
For more information on login and logout operations, see Login and Logout.
A conversation refers to a conversation with a user or a group. To send or receive messages in a one-to-one or group conversation, you need to first obtain the conversation by specifying the conversation type (one-to-one chat or group chat) and the peer’s identifier (the peer’s account or group ID).
Example of obtaining the one-to-one conversation with a recipient whose UserID is Windows-02
const void* user_data = nullptr; // Return of the callback function
const char* userid = "Windows-02";
int ret = TIMConvCreate(userid, kTIMConv_C2C, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
// The callback returns details about the conversation.
}, user_data);
if (ret != TIM_SUCC) {
// Failed to call the TIMConvCreate API
}
Example of obtaining the conversation with the group ID of Windows-Group-01
const void* user_data = nullptr; // Return of the callback function
const char* groupid = "Windows-Group-01";
int ret = TIMConvCreate(groupid, kTIMConv_Group, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
// The callback returns details about the conversation.
}, user_data);
if (ret != TIM_SUCC) {
// Failed to call the TIMConvCreate API
}
In the IM SDK, messages are represented by TIMMessage
. Each TIMMessage
consists of multiple TIMElem
objects. A TIMElem
object can be text or an image, which means a message can contain multiple objects including the text, image, and other objects.
Example:
const void* user_data = nullptr; // Return of the callback function
Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "Message Send to Windows-02";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);
const char* userid = "Windows-02";
int ret = TIMMsgSendNewMsg(userid, kTIMConv_C2C, json_value_msg.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
if (code != ERR_SUCC) {
// Failed to send the message
return;
}
// Sent the message successfully
}, user_data);
if (ret != TIM_SUCC) {
// Failed to call the TIMMsgSendNewMsg API
}
In most cases, users need to be notified of new messages. For this purpose, you simply need to register the new message notification callback TIMMessageListener
. When the user logs in, offline messages will be pulled. To avoid missing message notifications, register the listener callback for new messages before login.
Example of setting a message listener
// Sets a new message listener. When a new message arrives, a callback is triggered through this listener.
const void *user_data = nullptr;
TIMSetRecvNewMsgCallback([](const char* json_msg_array, const void* user_data) {
Json::Value json_value_msgs; // Parse the message
Json::Reader reader;
if (!reader.parse(json_msg_array, json_value_msgs)) {
printf("reader parse failure!%s", reader.getFormattedErrorMessages().c_str());
return;
}
for (Json::ArrayIndex i = 0; i < json_value_msgs.size(); i++) { // Traverse messages
Json::Value& json_value_msg = json_value_msgs[i];
Json::Value& elems = json_value_msg[kTIMMsgElemArray];
for (Json::ArrayIndex m = 0; m < elems.size(); m++) { // Traverse Elems
Json::Value& elem = elems[i];
uint32_t elem_type = elem[kTIMElemType].asUInt();
if (elem_type == TIMElemType::kTIMElem_Text) { // Text
}else if (elem_type == TIMElemType::kTIMElem_Sound) { // Audio
} else if (elem_type == TIMElemType::kTIMElem_File) { // File
} else if (elem_type == TIMElemType::kTIMElem_Image) { // Image
}
}
}
}, user_data);
For more information on receiving and sending messages, see Sending Messages and Receiving Messages.
There are multiple group types in IM. For information on their characteristics and limits, see the Group System. A group is identified by a unique ID, which allows for different operations. Group-related operations are implemented by TIMGroupManager
, which can be used after login.
Type | Description |
---|---|
Private | This is suitable for more private chat scenarios, where the group profile is not made public and a user can join the group only by being invited by a group member. Private groups are similar to groups in WeChat. |
Public | This is suitable for public chat scenarios. Public groups have a strict management and admission mechanism. |
ChatRoom | Chatroom members can join and quit freely. |
AVChatRoom | This is similar to ChatRoom, but supports an unlimited number of group members. |
BChatRoom | This is suitable for scenarios where messages are pushed to all online users. |
The following example shows how to create a public group named Windows-Group-Name and invite user Windows_002 to the group.
Example:
Json::Value json_group_member_array(Json::arrayValue);
// Initial group members
Json::Value json_group_member;
json_group_member[kTIMGroupMemberInfoIdentifier] = "Windows_002";
json_group_member[kTIMGroupMemberInfoMemberRole] = kTIMGroupMemberRoleFlag_Member;
json_group_member_array.append(json_group_member);
Json::Value json_value_createparam;
json_value_createparam[kTIMCreateGroupParamGroupId] = "Windows-Group-01";
json_value_createparam[kTIMCreateGroupParamGroupType] = kTIMGroup_Public;
json_value_createparam[kTIMCreateGroupParamGroupName] = "Windows-Group-Name";
json_value_createparam[kTIMCreateGroupParamGroupMemberArray] = json_group_member_array;
json_value_createparam[kTIMCreateGroupParamNotification] = "group notification";
json_value_createparam[kTIMCreateGroupParamIntroduction] = "group introduction";
json_value_createparam[kTIMCreateGroupParamFaceUrl] = "group face url";
json_value_createparam[kTIMCreateGroupParamMaxMemberCount] = 2000;
json_value_createparam[kTIMCreateGroupParamAddOption] = kTIMGroupAddOpt_Any;
const void* user_data = nullptr;
int ret = TIMGroupCreate(json_param.c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
if (code != ERR_SUCC) {
// Failed to create the group
return;
}
// Created the group successfully and parsed the JSON string to obtain the GroupID
}, user_data))
For more information on group operations, see Group APIs.
Group messages are similar to C2C (one-to-one chat) messages and require you to enter the group ID and group type kTIMConv_Group
when the message is sent. For more information, see Sending Messages in SDK documentation.
Was this page helpful?