无 UI 集成方案

服务端 API

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

消息介绍请参考 单聊消息群组消息消息格式描述

TIMMsgSendMessage

发送新消息。

原型

TIM_DECL int TIMMsgSendMessage(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_param, char* message_id_buffer, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msg_param const char* 消息 JSON 字符串
cb TIMCommCallback 发送新消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功,其他值表示接口调用失败。每个返回值的定义请参见 TIMResult
说明:

  • 发送新消息,单聊消息和群消息的发送均采用此接口。
  • 发送单聊消息时conv_id为对方的 UserID,conv_typekTIMConv_C2C
  • 发送群聊消息时conv_id为群 ID,conv_typekTIMConv_Group
  • 发送消息时不能发送kTIMElem_GroupTipskTIMElem_GroupReport,他们由为后台下发,用于更新(通知)群的信息。可以的发送消息内元素。
  • 文本消息元素,请参考 TextElem
  • 表情消息元素,请参考 FaceElem
  • 位置消息元素,请参考 LocationElem
  • 图片消息元素,请参考 ImageElem
  • 声音消息元素,请参考 SoundElem
  • 自定义消息元素,请参考 CustomElem
  • 文件消息元素,请参考 FileElem
  • 视频消息元素,请参考 VideoElem

示例

Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "send text";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);

const size_t kMessageIDLength = 128;
char message_id_buffer[kMessageIDLength] = {0};
int ret = TIMMsgSendMessage(conv_id.c_str(), kTIMConv_C2C, json_value_msg.toStyledString().c_str(), message_id_buffer, 
    [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (ERR_SUCC != code) {
        // 消息发送失败
        return;
    }
    // 消息发送成功
}, nullptr);

// json_value_msg.toStyledString().c_str() 得到 json_msg_param JSON 字符串如下
{
   "message_id" : "14400111550110000_1551446728_45598731"
   "message_client_time" : 1551446728,
   "message_elem_array" : [
      {
         "elem_type" : 0,
         "text_elem_content" : "send text"
      }
   ],
   "message_sender" : "user1",
   "message_server_time" : 1551446728
}

TIMMsgSendNewMsg

发送新消息。(待废弃,请使用 TIMMsgSendMessage 接口)

原型

TIM_DECL int TIMMsgSendNewMsg(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msg_param const char* 消息 JSON 字符串
cb TIMCommCallback 发送新消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

  • 发送新消息,单聊消息和群消息的发送均采用此接口。
    • 发送单聊消息时conv_id为对方的 UserID,conv_typekTIMConv_C2C
    • 发送群聊消息时conv_id为群 ID,conv_typekTIMConv_Group
  • 发送消息时不能发送kTIMElem_GroupTipskTIMElem_GroupReport,他们由为后台下发,用于更新(通知)群的信息。可以的发送消息内元素。

示例

Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "send text";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);

int ret = TIMMsgSendNewMsg(conv_id.c_str(), kTIMConv_C2C, json_value_msg.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (ERR_SUCC != code) {
        // 消息发送失败
        return;
    }
    // 消息发送成功
}, this);

// json_value_msg.toStyledString().c_str() 得到 json_msg_param JSON 字符串如下
{
   "message_client_time" : 1551446728,
   "message_elem_array" : [
      {
         "elem_type" : 0,
         "text_elem_content" : "send text"
      }
   ],
   "message_sender" : "user1",
   "message_server_time" : 1551446728
}

TIMMsgCancelSend

根据消息 messageID 取消发送中的消息。

原型

TIM_DECL int TIMMsgCancelSend(const char* conv_id, enum TIMConvType conv_type, const char* message_id, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
message_id const char* 消息 ID
cb TIMCommCallback 取消结果的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功,其他值表示接口调用失败。每个返回值的定义请参见 TIMResult

示例

TIMMsgCancelSend("test_win_03", kTIMConv_C2C, "message_id_1", [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

TIMMsgFindMessages

根据消息 messageID 查询本地的消息列表。

原型

TIM_DECL int TIMMsgFindMessages(const char* json_message_id_array, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
json_message_id_array const char* 消息 ID 列表
cb TIMCommCallback 根据消息定位精准查找指定会话的消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功,其他值表示接口调用失败。每个返回值的定义请参见 TIMResult

示例

Json::Value json_message_id_1("id_clienttime_rand_1");
Json::Value json_message_id_2("id_clienttime_rand_2");

Json::Value json_message_id_array;
json_message_id_array.append(json_message_id_1);
json_message_id_array.append(json_message_id_2);
TIMMsgFindMessages(json_message_id_array.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_message_id_array.toStyledString().c_str() 的到 json_message_id_array JSON 字符串如下
[
   "id_clienttime_rand_1",
   "id_clienttime_rand_2",
]

TIMMsgReportReaded

消息上报已读。

原型

TIM_DECL int TIMMsgReportReaded(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID,从 5.8 版本开始,当 conv_id 为 NULL 空字符串指针或者""空字符串时,标记 conv_type 表示的所有单聊消息或者群组消息为已读状态
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msg_param const char* 消息 JSON 字符串
cb TIMCommCallback 消息上报已读成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

json_msg_param可以填NULL空字符串指针或者""空字符串,此时以会话当前最新消息的时间戳(如果会话存在最新消息)或当前时间为已读时间戳上报。当要指定消息时,则以该指定消息的时间戳为已读时间戳上报,最好用接收新消息获取的消息数组里面的消息 JSON 或者用消息定位符查找到的消息 JSON,避免重复构造消息 JSON。

TIMMsgMarkAllMessageAsRead

标记所有消息为已读(5.8及其以上版本支持)。

原型

TIM_DECL int TIMMsgMarkAllMessageAsRead(TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
cb TIMCommCallback 成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功,其他值表示接口调用失败。每个返回值的定义请参见 TIMResult

TIMMsgRevoke

消息撤回。

原型

TIM_DECL int TIMMsgRevoke(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msg_param const char* 消息 JSON 字符串
cb TIMCommCallback 消息撤回成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

消息撤回。使用保存的消息 JSON 或者用消息定位符查找到的消息 JSON,避免重复构造消息 JSON。

示例

Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "send text";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);

int ret = TIMMsgSendNewMsg("test_win_03", kTIMConv_C2C, json_value_msg.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (ERR_SUCC != code) {
        // 消息发送失败
        return;
    }
    // 消息发送成功 json_param 返回发送后的消息 JSON 字符串
    TIMMsgRevoke("test_win_03", kTIMConv_C2C, json_param, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
        if (ERR_SUCC != code) {
            // 消息撤回失败
            return;
        }
        // 消息撤回成功

    }, user_data);
}, this);

TIMMsgFindByMsgLocatorList

根据消息定位精准查找指定会话的消息。

原型

TIM_DECL int TIMMsgFindByMsgLocatorList(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_Locator_array, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msg_Locator_array const char* 消息定位符数组
cb TIMCommCallback 根据消息定位精准查找指定会话的消息成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

  • 此接口根据消息定位符精准查找指定会话的消息,该功能一般用于消息撤回时查找指定消息等。
  • 一个消息定位符对应一条消息。

示例

Json::Value json_msg_locator;                      //一条消息对应一个消息定位符(精准定位)
json_msg_locator[kTIMMsgLocatorIsRevoked] = false; //消息是否被撤回
json_msg_locator[kTIMMsgLocatorTime] = 123;        //填入消息的时间
json_msg_locator[kTIMMsgLocatorSeq] = 1;           
json_msg_locator[kTIMMsgLocatorIsSelf] = false;    
json_msg_locator[kTIMMsgLocatorRand] = 12345678;   

Json::Value json_msg_locators;
json_msg_locators.append(json_msg_locator);
TIMMsgFindByMsgLocatorList("user2", kTIMConv_C2C, json_msg_locators.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_msg_locators.toStyledString().c_str() 的到 json_msg_Locator_array JSON 字符串如下
[
   {
      "message_locator_is_revoked" : false,
      "message_locator_is_self" : false,
      "message_locator_rand" : 12345678,
      "message_locator_seq" : 1,
      "message_locator_time" : 123
   }
]

TIMMsgImportMsgList

导入消息列表到指定会话。

原型

TIM_DECL int TIMMsgImportMsgList(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_array, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msg_array const char* 消息数组
cb TIMCommCallback 导入消息列表到指定会话成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

批量导入消息,可以自己构造消息去导入。也可以将之前要导入的消息数组 JSON 保存,然后导入的时候直接调用接口,避免构造消息数组。

示例

Json::Value json_value_elem; //构造消息文本元素
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is import msg";

Json::Value json_value_msg; //构造消息
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);
json_value_msg[kTIMMsgElemArray].append(json_value_elem);

Json::Value json_value_msgs;  //消息数组
json_value_msgs.append(json_value_msg);

TIMMsgImportMsgList("user2", kTIMConv_C2C, json_value_msgs.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_value_msgs.toStyledString().c_str() 得到 json_msg_array JSON 字符串如下
[
   {
      "message_client_time" : 1551446728,
      "message_elem_array" : [
         {
            "elem_type" : 0,
            "text_elem_content" : "this is import msg"
         }
      ],
      "message_sender" : "user1",
      "message_server_time" : 1551446728
   }
]

TIMMsgSaveMsg

保存自定义消息。

原型

TIM_DECL int TIMMsgSaveMsg(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msg_param const char* 消息 JSON 字符串
cb TIMCommCallback 保存自定义消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

消息保存接口,一般是自己构造一个消息 JSON 字符串,然后保存到指定会话。

TIMMsgGetMsgList

获取指定会话的消息列表。

原型

TIM_DECL int TIMMsgGetMsgList(const char* conv_id, enum TIMConvType conv_type, const char* json_get_msg_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_get_msg_param const char* 消息获取参数
cb TIMCommCallback 获取指定会话的消息列表成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

  • 从 kTIMMsgGetMsgListParamLastMsg 指定的消息开始获取本地消息列表,kTIMMsgGetMsgListParamCount 为要获取的消息数目。kTIMMsgGetMsgListParamLastMsg 可以不指定,不指定时表示以会话最新的消息为 LastMsg 。
  • 若指定 kTIMMsgGetMsgListParamIsRamble 为true则本地消息获取不够指定数目时,会去获取云端漫游消息。
  • kTIMMsgGetMsgListParamIsForward 为true时表示获取比 kTIMMsgGetMsgListParamLastMsg 新的消息,为false时表示获取比 kTIMMsgGetMsgListParamLastMsg 旧的消息
  • 拉取 kTIMConv_C2C 消息时,只能使用 kTIMMsgGetMsgListParamLastMsg 作为消息的拉取起点;如果没有指定 kTIMMsgGetMsgListParamLastMsg,默认使用会话的最新消息作为拉取起点

  • 拉取 kTIMConv_Group 消息时,除了可以使用 kTIMMsgGetMsgListParamLastMsg 作为消息的拉取起点外,也可以使用 kTIMMsgGetMsgListParamLastMsgSeq 来指定消息的拉取起点,二者的区别在于:

  • 使用 kTIMMsgGetMsgListParamLastMsg 作为消息的拉取起点时,返回的消息列表里不包含 kTIMMsgGetMsgListParamLastMsg;

  • 使用 kTIMMsgGetMsgListParamLastMsgSeq 作为消息拉取起点时,返回的消息列表里包含 kTIMMsgGetMsgListParamLastMsgSeq 所表示的消息;

  • 在拉取 kTIMConv_Group 消息时

  • 如果同时指定了 kTIMMsgGetMsgListParamLastMsg 和 kTIMMsgGetMsgListParamLastMsgSeq,SDK 优先使用 kTIMMsgGetMsgListParamLastMsg 作为消息的拉取起点

  • 如果 kTIMMsgGetMsgListParamLastMsg 和 kTIMMsgGetMsgListParamLastMsgSeq,SDK 都未指定,消息的拉取起点分为如下两种情况:

  • 如果设置了拉取的时间范围,SDK 会根据 kTIMMsgGetMsgListParamTimeBegin 所描述的时间点作为拉取起点

  • 如果未设置拉取的时间范围,SDK 默认使用会话的最新消息作为拉取起点

示例:获取 C2C 会话Windows-02消息列表

Json::Value json_msg(Json::objectValue); // 构造 Message
Json::Value json_get_msg_param;
json_get_msg_param[kTIMMsgGetMsgListParamLastMsg] = json_msg;
json_get_msg_param[kTIMMsgGetMsgListParamIsRamble] = false;
json_get_msg_param[kTIMMsgGetMsgListParamIsForward] = true;
json_get_msg_param[kTIMMsgGetMsgListParamCount] = 100;

int ret = TIMMsgGetMsgList("Windows-02", kTIMConv_C2C, json_get_msg_param.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
}, this);

// json_get_msg_param.toStyledString().c_str() 得到 json_get_msg_param JSON 字符串如下
{
   "msg_getmsglist_param_count" : 100,
   "msg_getmsglist_param_is_forward" : true,
   "msg_getmsglist_param_is_remble" : false,
   "msg_getmsglist_param_last_msg" : {}
}

TIMMsgDelete

删除指定会话的消息。

原型

TIM_DECL int TIMMsgDelete(const char* conv_id, enum TIMConvType conv_type, const char* json_msgdel_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msgdel_param const char* 消息获取参数
cb TIMCommCallback 删除指定会话的消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

Json::Value json_value_msg(Json::objectValue);
Json::Value json_value_msgdelete;
json_value_msgdelete[kTIMMsgDeleteParamIsRamble] = false;
json_value_msgdelete[kTIMMsgDeleteParamMsg] = json_value_msg;
TIMMsgDelete("user2", kTIMConv_C2C, json_value_msgdelete.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

// json_value_msgdelete.toStyledString().c_str() 得到 json_msgdel_param JSON 字符串如下
{
  "msg_delete_param_is_remble" : false,
  "msg_delete_param_msg" : {}
}

TIMMsgListDelete

删除指定会话的本地及漫游消息列表。

原型

TIM_DECL int TIMMsgListDelete(const char* conv_id, enum TIMConvType conv_type, const char* json_msg_array, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
json_msg_array const char* 消息数组
cb TIMCommCallback 删除指定会话的消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

  • 本接口会在删除本地消息的同时也会删除漫游消息。需要注意以下几点:
  • > 建议将之前的消息数组Json保存,然后删除的时候直接调用接口,避免构造消息数组。
  • > 一次最多只能删除 30 条消息。
  • > 一秒钟最多只能调用一次该接口。
  • > 如果该帐号在其他设备上拉取过这些消息,那么调用该接口删除后,这些消息仍然会保存在那些设备上,即删除消息不支持多端同步。

示例

Json::Value json_value_elem; //构造消息文本元素
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is import msg";

Json::Value json_value_msg; //构造消息
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);
json_value_msg[kTIMMsgElemArray].append(json_value_elem);

Json::Value json_value_msgs;  //消息数组
json_value_msgs.append(json_value_msg);

TIMMsgListDelete("user2", kTIMConv_C2C, json_value_msgs.toStyledString().c_str(), [](int32_t code, const chardesc, const charjson_param, const voiduser_data) {

}, nullptr);

// json_value_msgs.toStyledString().c_str() 得到json_msg_array JSON 字符串如下
[
   {
      "message_client_time" : 1551446728,
      "message_elem_array" : [
         {
            "elem_type" : 0,
            "text_elem_content" : "I will be deleted"
         }
      ],
      "message_sender" : "user1",
      "message_server_time" : 1551446728
   }
]

TIMMsgClearHistoryMessage

清空指定会话的消息。

原型

TIM_DECL int TIMMsgClearHistoryMessage(const char* conv_id, enum TIMConvType conv_type, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
conv_id const char* 会话的 ID
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
cb TIMCommCallback 清空成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

TIMMsgClearHistoryMessage("user2", kTIMConv_C2C, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, nullptr);

TIMMsgSetC2CReceiveMessageOpt

设置针对某个用户的 C2C 消息接收选项(支持批量设置)。

原型

TIM_DECL int TIMMsgSetC2CReceiveMessageOpt(const char* json_identifier_array, TIMReceiveMessageOpt opt, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
json_identifier_array const char* 用户 ID 列表
opt TIMReceiveMessageOpt 消息接收选项,请参考TIMReceiveMessageOpt
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
cb TIMCommCallback 设置成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

  • 该接口支持批量设置,您可以通过参数 userIDList 设置一批用户,但一次最大允许设置 30 个用户。
  • 该接口调用频率被限制为1秒内最多调用5次。

示例

Json::Value json_identifier_array(Json::arrayValue);
json_identifier_array.append("user1");
json_identifier_array.append("user2");

TIMMsgSetC2CReceiveMessageOpt(json_identifier_array.toStyledString().c_str(), kTIMRecvMsgOpt_Receive, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgGetC2CReceiveMessageOpt

查询针对某个用户的 C2C 消息接收选项。

原型

TIM_DECL int TIMMsgGetC2CReceiveMessageOpt(const char* json_identifier_array, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
json_identifier_array const char* 用户 ID 列表
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
cb TIMCommCallback 查询结果的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

Json::Value json_identifier_array(Json::arrayValue);
json_identifier_array.append("user1");
json_identifier_array.append("user2");

TIMMsgGetC2CReceiveMessageOpt(json_identifier_array.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

// 回调的 json_param 示例。Json Key请参考[GetC2CRecvMsgOptResult](TIMCloudDef.h)
[
   {
      "msg_recv_msg_opt_result_identifier" : "user1",
      "msg_recv_msg_opt_result_opt" : 0,
   },
   {
      "msg_recv_msg_opt_result_identifier" : "user2",
      "msg_recv_msg_opt_result_opt" : 1,
   }
]

TIMMsgSetGroupReceiveMessageOpt

设置群消息的接收选项。

原型

TIM_DECL int TIMMsgSetGroupReceiveMessageOpt(const char* group_id, TIMReceiveMessageOpt opt, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
group_id const char* 群 ID
opt enum TIMReceiveMessageOpt 消息接收选项,请参考TIMReceiveMessageOpt
conv_type enum TIMConvType 会话类型,请参考 TIMConvType
cb TIMCommCallback 设置成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

  • 查询群消息的接收选项:您可以在群资料(GroupBaseInfo)中获得这个信息

示例

TIMMsgSetGroupReceiveMessageOpt("group_id", kTIMRecvMsgOpt_Receive, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgDownloadElemToPath

下载消息内元素到指定文件路径(图片、视频、音频、文件)。

原型

TIM_DECL int TIMMsgDownloadElemToPath(const char* json_download_elem_param, const char* path, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
json_download_elem_param const char* 下载的参数 JSON 字符串
path const char* 下载文件保存路径
cb TIMCommCallback 下载成功与否的回调以及下载进度回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

此接口用于下载消息内图片、文件、声音、视频等元素。下载的参数kTIMMsgDownloadElemParamFlag、kTIMMsgDownloadElemParamId、kTIMMsgDownloadElemParamBusinessId、kTIMMsgDownloadElemParamUrl 均可以在相应元素内找到。其中kTIMMsgDownloadElemParamType为下载文件类型 TIMDownloadType

示例

Json::Value download_param;
download_param[kTIMMsgDownloadElemParamFlag] = flag;
download_param[kTIMMsgDownloadElemParamType] = type;
download_param[kTIMMsgDownloadElemParamId] = id;
download_param[kTIMMsgDownloadElemParamBusinessId] = business_id;
download_param[kTIMMsgDownloadElemParamUrl] = url;

TIMMsgDownloadElemToPath(download_param.toStyledString().c_str(), (path_ + "\\" + name).c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgDownloadMergerMessage

下载合并消息。

原型

TIM_DECL int TIMMsgDownloadMergerMessage(const char* json_single_msg, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
json_single_msg const char* 单条消息的 JSON 字符串,接收消息、查找消息或查询历史消息时获取到的消息
cb TIMCommCallback 下载成功与否的回调以及下载进度回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

// 接收一条消息 json_single_msg 
TIMMsgDownloadMergerMessage(json_single_msg, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {

}, this);

TIMMsgSearchLocalMessages

本地消息搜索,提升 App 使用体验必备功能,可以帮助用户从纷繁复杂的信息中直接找到预期内容,快捷方便;也可作为运营工具,增加相关内容的引导,简洁高效。

注意:

本地消息搜索,限5.4.666及以上版本支持,并且需要 购买旗舰版套餐包 后使用,详见 价格说明

原型

TIM_DECL int TIMMsgSearchLocalMessages(const char* json_search_message_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
json_search_message_param const char* 消息搜索参数
cb TIMCommCallback 搜索成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

// 接收一条消息 json_single_msg 
Json::Value json_search_message_param;
json_search_message_param[kTIMMsgSearchParamKeywordArray].append("keyword1");
json_search_message_param[kTIMMsgSearchParamKeywordArray].append("keyword2");
json_search_message_param[kTIMMsgSearchParamMessageTypeArray].append(kTIMElem_Text);
json_search_message_param[kTIMMsgSearchParamMessageTypeArray].append(kTIMElem_Image);
json_search_message_param[kTIMMsgSearchParamConvId] = "xxxxx";
json_search_message_param[kTIMMsgSearchParamConvType] = kTIMConv_Group;
json_search_message_param[kTIMMsgSearchParamPageIndex] = 0;
json_search_message_param[kTIMMsgSearchParamPageSize] = 10;

int ret = TIMMsgSearchLocalMessages(json_search_message_param.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {

}, this);

// json_search_message_param.toStyledString().c_str() 得到 json_search_message_param JSON 字符串如下
{
   "msg_search_param_keyword_array" : ["keyword1", "keyword2"],
   "msg_search_param_message_type_array" : [0, 1],
   "msg_search_param_page_index" : 0,
   "msg_search_param_page_size" : 10
}

TIMMsgSetLocalCustomData

设置消息自定义数据(本地保存,不会发送到对端,程序卸载重装后失效)。

原型

TIM_DECL int TIMMsgSetLocalCustomData(const char* json_msg_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
json_msg_param const char* 消息json字符串
cb TIMCommCallback 保存自定义消息成功与否的回调。回调函数定义请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

// 接收一条消息 json_single_msg 
Json::Value json_parameters;
json_parameters[kTIMMsgGetMsgListParamIsRamble] = true;
json_parameters[kTIMMsgGetMsgListParamIsForward] = false;
json_parameters[kTIMMsgGetMsgListParamCount] = 1;
 TIMMsgGetMsgList("98826", kTIMConv_C2C, json_parameters.toStyledString().c_str(),
    [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
        Json::Reader json_reader;
        json::Array json_message_array;
        json_reader.parse(json_params, json_message_array);
        if (json_message_array.size() > 0) {
            Json::Value json_obj_msg = json_message_array[0];
            json_obj_msg[kTIMMsgCustomStr] = "custom Str";
            json_obj_msg[kTIMMsgCustomInt] = "custom int";
            TIMMsgSetLocalCustomData(json_obj_msg.toStyledString().c_str(),
                [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
                    printf("TIMMsgSetLocalCustomData complete|code:%d|desc:%s\n", code, desc);
                }, nullptr);
        }
}, nullptr);

TIMMsgBatchSend

群发消息,该接口不支持向群组发送消息。

原型

TIM_DECL int TIMMsgBatchSend(const char* json_batch_send_param, TIMCommCallback cb, const void* user_data);

参数

参数 类型 含义
json_batch_send_param const char* 群发消息 JSON 字符串
cb TIMCommCallback 群发消息成功与否的回调。回调函数定义和参数解析请参考 TIMCommCallback
user_data const void* 用户自定义数据,IM SDK 只负责传回给回调函数 cb,不做任何处理

返回值

类型 含义
int 返回 TIM_SUCC 表示接口调用成功(接口只有返回 TIM_SUCC,回调 cb 才会被调用),其他值表示接口调用失败。每个返回值的定义请参考 TIMResult
说明:

批量发送消息的接口,每个 UserID 发送成功与否,通过回调 cb 返回。

示例

//构造消息文本元素
Json::Value json_value_elem;
json_value_elem[kTIMElemType] = TIMElemType::kTIMElem_Text;
json_value_elem[kTIMTextElemContent] = "this is batch send msg";
//构造消息
Json::Value json_value_msg;
json_value_msg[kTIMMsgSender] = login_id;
json_value_msg[kTIMMsgClientTime] = time(NULL);
json_value_msg[kTIMMsgServerTime] = time(NULL);
json_value_msg[kTIMMsgElemArray].append(json_value_elem);

// 构造批量发送 ID 数组列表
Json::Value json_value_ids(Json::arrayValue);
json_value_ids.append("user2");
json_value_ids.append("user3");
// 构造批量发送接口参数
Json::Value json_value_batchsend;
json_value_batchsend[kTIMMsgBatchSendParamIdentifierArray] = json_value_ids;
json_value_batchsend[kTIMMsgBatchSendParamMsg] = json_value_msg;
int ret = TIMMsgBatchSend(json_value_batchsend.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
}, nullptr);

// json_value_batchsend.toStyledString().c_str() 得到 json_batch_send_param JSON 字符串如下
{
   "msg_batch_send_param_identifier_array" : [ "user2", "user3" ],
   "msg_batch_send_param_msg" : {
      "message_client_time" : 1551340614,
      "message_elem_array" : [
         {
            "elem_type" : 0,
            "text_elem_content" : "this is batch send msg"
         }
      ],
      "message_sender" : "user1",
      "message_server_time" : 1551340614
   }
}

目录