API Overview

Last updated: 2020-08-03 11:16:35

    IM SDK Event Callbacks

    TIMRecvNewMsgCallback

    Callback for new messages.

    Prototype

    typedef void (*TIMRecvNewMsgCallback)(const char* json_msg_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_msg_array Const char* New message array
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    This callback is used to obtain the newly received message array. Note that the elements in the message are also an array, and each element is defined by elem_type.

    Example 1: parse the message array.

    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 the 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 the elements.
            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) {  // Sound
    
            } else if (elem_type == TIMElemType::kTIMElem_File) {  // File
    
            } else if (elem_type == TIMElemType::kTIMElem_Image) { // Image
    
            } else if (elem_type == TIMElemType::kTIMElem_Custom) { // Custom element
    
            } else if (elem_type == TIMElemType::kTIMElem_GroupTips) { // Group system message
    
            } else if (elem_type == TIMElemType::kTIMElem_Face) { // Emoji
    
            } else if (elem_type == TIMElemType::kTIMElem_Location) { // Location
    
            } else if (elem_type == TIMElemType::kTIMElem_GroupReport) { // Group system notification
    
            } else if (elem_type == TIMElemType::kTIMElem_Video) { // Video
    
            }
        }
    }

    Example 2: return the JSON string of a text message. For details on the JSON keys, see Message and TextElem.

    [
       {
          "message_client_time" : 1551080111,
          "message_conv_id" : "user2",
          "message_conv_type" : 1,
          "message_elem_array" : [
             {
                "elem_type" : 0,
                "text_elem_content" : "123213213"
             }
          ],
          "message_is_from_self" : true,
          "message_is_read" : true,
          "message_rand" : 2130485001,
          "message_sender" : "user1",
          "message_seq" : 1,
          "message_server_time" : 1551080111,
          "message_status" : 2
       }
    ]

    Example 3: return the JSON string of a group notification. For details on the JSON keys, see Message and GroupReportElem.

    [
       {
          "message_client_time" : 1551344977,
          "message_conv_id" : "",
          "message_conv_type" : 3,
          "message_elem_array" : [
             {
                "elem_type" : 9,
                "group_report_elem_group_id" : "first group id",
                "group_report_elem_group_name" : "first group name",
                "group_report_elem_msg" : "",
                "group_report_elem_op_group_memberinfo" : {
                   "group_member_info_custom_info" : {},
                   "group_member_info_identifier" : "user1",
                   "group_member_info_join_time" : 0,
                   "group_member_info_member_role" : 0,
                   "group_member_info_msg_flag" : 0,
                   "group_member_info_msg_seq" : 0,
                   "group_member_info_name_card" : "",
                   "group_member_info_shutup_time" : 0
                },
                "group_report_elem_op_user" : "",
                "group_report_elem_platform" : "Windows",
                "group_report_elem_report_type" : 6,
                "group_report_elem_user_data" : ""
             }
          ],
          "message_is_from_self" : false,
          "message_is_read" : true,
          "message_rand" : 2207687390,
          "message_sender" : "@TIM#SYSTEM",
          "message_seq" : 1,
          "message_server_time" : 1551344977,
          "message_status" : 2
       }
    ]

    Example 4: return the JSON string of a group tip. For details on the JSON keys, see Message and GroupTipsElem.

    [
       {
          "message_client_time" : 1551412814,
          "message_conv_id" : "first group id",
          "message_conv_type" : 2,
          "message_elem_array" : [
             {
                "elem_type" : 6,
                "group_tips_elem_changed_group_memberinfo_array" : [],
                "group_tips_elem_group_change_info_array" : [
                   {
                      "group_tips_group_change_info_flag" : 10,
                      "group_tips_group_change_info_value" : "first group name to other name"
                   }
                ],
                "group_tips_elem_group_id" : "first group id",
                "group_tips_elem_group_name" : "first group name to other name",
                "group_tips_elem_member_change_info_array" : [],
                "group_tips_elem_member_num" : 0,
                "group_tips_elem_op_group_memberinfo" : {
                   "group_member_info_custom_info" : {},
                   "group_member_info_identifier" : "user1",
                   "group_member_info_join_time" : 0,
                   "group_member_info_member_role" : 0,
                   "group_member_info_msg_flag" : 0,
                   "group_member_info_msg_seq" : 0,
                   "group_member_info_name_card" : "",
                   "group_member_info_shutup_time" : 0
                },
                "group_tips_elem_op_user" : "user1",
                "group_tips_elem_platform" : "Windows",
                "group_tips_elem_time" : 0,
                "group_tips_elem_tip_type" : 6,
                "group_tips_elem_user_array" : []
             }
          ],
          "message_is_from_self" : false,
          "message_is_read" : true,
          "message_rand" : 1,
          "message_sender" : "@TIM#SYSTEM",
          "message_seq" : 1,
          "message_server_time" : 1551412814,
          "message_status" : 2
       },
    ]

    TIMMsgReadedReceiptCallback

    Callback for message read receipt.

    Prototype

    typedef void (*TIMMsgReadedReceiptCallback)(const char* json_msg_readed_receipt_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_msg_readed_receipt_array Const char* Message read receipt array
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Sample

    void MsgReadedReceiptCallback(const char* json_msg_readed_receipt_array, const void* user_data) {
        Json::Value json_value_receipts;
        Json::Reader reader;
        if (!reader.parse(json_msg_readed_receipt_array, json_value_receipts)) {
            // Failed to parse the JSON string.
            return;
        }
    
        for (Json::ArrayIndex i = 0; i < json_value_receipts.size(); i++) {
            Json::Value& json_value_receipt = json_value_receipts[i];
    
            std::string convid = json_value_receipt[kTIMMsgReceiptConvId].asString();
            uint32_t conv_type = json_value_receipt[kTIMMsgReceiptConvType].asUInt();
            uint64_t timestamp = json_value_receipt[kTIMMsgReceiptTimeStamp].asUInt64();
    
            // Message read logic
        }
    }

    TIMMsgRevokeCallback

    Callback for revoking received messages.

    Prototype

    typedef void (*TIMMsgRevokeCallback)(const char* json_msg_locator_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_msg_locator_array Const char* Message locator array
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Sample

    void MsgRevokeCallback(const char* json_msg_locator_array, const void* user_data) {
        Json::Value json_value_locators;
        Json::Reader reader;
        if (!reader.parse(json_msg_locator_array, json_value_locators)) {
            // Failed to parse the JSON string.
            return;
        }
        for (Json::ArrayIndex i = 0; i < json_value_locators.size(); i++) {
            Json::Value& json_value_locator = json_value_locators[i];
    
            std::string convid = json_value_locator[kTIMMsgLocatorConvId].asString();
            uint32_t conv_type = json_value_locator[kTIMMsgLocatorConvType].asUInt();
            bool isrevoke      = json_value_locator[kTIMMsgLocatorIsRevoked].asBool();
            uint64_t time      = json_value_locator[kTIMMsgLocatorTime].asUInt64();
            uint64_t seq       = json_value_locator[kTIMMsgLocatorSeq].asUInt64();
            uint64_t rand      = json_value_locator[kTIMMsgLocatorRand].asUInt64();
            bool isself        = json_value_locator[kTIMMsgLocatorIsSelf].asBool();
    
            // Message revocation logic
        }
    }

    TIMMsgElemUploadProgressCallback

    Callback for checking the progress of uploading files pertaining to message elements.

    Prototype

    typedef void (*TIMMsgElemUploadProgressCallback)(const char* json_msg, uint32_t index, uint32_t cur_size, uint32_t total_size, const void* user_data);

    Parameters

    Parameter Type Description
    json_msg Const char* New message
    index Uint32_t Subscript of the uploaded element Elem in the json_msg message
    cur_size Uint32_t Current size uploaded
    total_size Uint32_t Total size uploaded
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Sample

    void MsgElemUploadProgressCallback(const char* json_msg, uint32_t index, uint32_t cur_size, uint32_t total_size, const void* user_data) {
        Json::Value json_value_msg;
        Json::Reader reader;
        if (!reader.parse(json_msg, json_value_msg)) {
            // Failed to parse the JSON string.
            return;
        }
        Json::Value& elems = json_value_msg[kTIMMsgElemArray];
        if (index >= elems.size()) {
            // The value of index exceeds the number of message elements.
            return;
        }
        uint32_t elem_type = elems[index][kTIMElemType].asUInt();
        if (kTIMElem_File ==  elem_type) {
    
        }
        else if (kTIMElem_Sound == elem_type) {
    
        }
        else if (kTIMElem_Video == elem_type) {
    
        }
        else if (kTIMElem_Image == elem_type) {
    
        }
        else {
            // Other types of elements do not meet the upload requirements.
        }
    }

    TIMGroupTipsEventCallback

    Callback for group events.

    Prototype

    typedef void (*TIMGroupTipsEventCallback)(const char* json_group_tip_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_group_tip_array const char* Group tip list
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    TIMConvEventCallback

    Callback for conversation events.

    Prototype

    typedef void (*TIMConvEventCallback)(enum TIMConvEvent conv_event, const char* json_conv_array, const void* user_data);

    Parameters

    Parameter Type Description
    conv_event Enum TIMConvEvent Conversation event type. For details, see TIMConvEvent.
    json_conv_array Const char* Conversation information list
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Example: parse the conversation event callback data.

    void ConvEventCallback(TIMConvEvent conv_event, const char* json_conv_array, const void* user_data) {
        Json::Reader reader;
        Json::Value json_value;
        if (!reader.parse(json_conv_array, json_value)) {
            // Failed to parse the JSON string.
            return;
        }
        for (Json::ArrayIndex i = 0; i < json_value.size(); i++) { // Traverse the conversation types.
            Json::Value& convinfo = json_value[i];
            // Identifies the conversation event type.
            if (conv_event == kTIMConvEvent_Add) {
    
            }
            else if (conv_event == kTIMConvEvent_Del) {
    
            }
            else if (conv_event == kTIMConvEvent_Update) {
    
            }
        }
    }

    TIMNetworkStatusListenerCallback

    Callback for the network connection status.

    Prototype

    typedef void (*TIMNetworkStatusListenerCallback)(enum TIMNetworkStatus status, int32_t code, const char* desc, const void* user_data);

    Parameters

    Parameter Type Description
    status Enum TIMNetworkStatus Network status. For details, see TIMNetworkStatus.
    code Int32_t ERR_SUCC: succeeded. Others: failed. For details, see Error Codes.
    desc Const char* String of the error description
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Example: process the callback for monitoring the network status.

    void NetworkStatusListenerCallback(TIMNetworkStatus status, int32_t code, const char* desc, const void* user_data) {
        switch(status) {
        case kTIMConnected: {
            printf("OnConnected ! user_data:0x%08x", user_data);
            break;
        }
        case kTIMDisconnected:{
            printf("OnDisconnected ! user_data:0x%08x", user_data);
            break;
        }
        case kTIMConnecting:{
            printf("OnConnecting ! user_data:0x%08x", user_data);
            break;
        }
        case kTIMConnectFailed:{
            printf("ConnectFailed code:%u desc:%s ! user_data:0x%08x", code, desc, user_data);
            break;
        }
        }
    }

    TIMKickedOfflineCallback

    Callback for forced logout.

    Prototype

    typedef void (*TIMKickedOfflineCallback)(const void* user_data);

    Parameters

    Parameter Type Description
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    TIMUserSigExpiredCallback

    Callback for user ticket expiration.

    Prototype

    typedef void (*TIMUserSigExpiredCallback)(const void* user_data);

    Parameters

    Parameter Type Description
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    TIMOnAddFriendCallback

    Callback for adding friends.

    Prototype

    typedef void(*TIMOnAddFriendCallback)(const char* json_identifier_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_identifier_array Const char* List of added friends
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Example: json_identifier_array

    [ "user15" ]

    TIMOnDeleteFriendCallback

    Callback for deleting friends.

    Prototype

    typedef void(*TIMOnDeleteFriendCallback)(const char* json_identifier_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_identifier_array Const char* List of deleted friends
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Example: json_identifier_array

    [ "user15" ]

    TIMUpdateFriendProfileCallback

    Callback for updating friend profiles.

    Prototype

    typedef void(*TIMUpdateFriendProfileCallback)(const char* json_friend_profile_update_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_friend_profile_update_array Const char* Friend profile update list
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Example: json_friend_profile_update_array

    [
       {
          "friend_profile_update_identifier" : "user4",
          "friend_profile_update_item" : {
             "friend_profile_item_group_name_array" : [ "group1", "group2" ],
             "friend_profile_item_remark" : "New Remark"
          }
       }
    ]

    TIMFriendAddRequestCallback

    Callback for friend requests.

    Prototype

    typedef void(*TIMFriendAddRequestCallback)(const char* json_friend_add_request_pendency_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_friend_add_request_pendency_array Const char* List of pending friend requests
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    Example: json_friend_add_request_pendency_array

    [
       {
          "friend_add_pendency_add_source" : "AddSource_Type_android",
          "friend_add_pendency_add_wording" : "aaaa",
          "friend_add_pendency_identifier" : "v222",
          "friend_add_pendency_nick_name" : ""
       }
    ]

    TIMLogCallback

    Callback for logs.

    Prototype

    typedef void (*TIMLogCallback)(enum TIMLogLevel level, const char* log, const void* user_data);

    Parameters

    Parameter Type Description
    level Enum TIMLogLevel Log level. For details, see TIMLogLevel.
    log const char* Log string
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    TIMMsgUpdateCallback

    Callback for message updating.

    Prototype

    typedef void (*TIMMsgUpdateCallback)(const char* json_msg_array, const void* user_data);

    Parameters

    Parameter Type Description
    json_msg_array const char* Updated message array
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    For details, see TIMRecvNewMsgCallback.

    IM SDK API Callbacks

    TIMCommCallback

    Definition of common API callbacks.

    Prototype

    typedef void (*TIMCommCallback)(int32_t code, const char* desc, const char* json_params, const void* user_data);

    Parameters

    Parameter Type Description
    code Int32_t ERR_SUCC: succeeded. Others: failed. For details, see Error Codes.
    desc Const char* String of the error description
    json_params Const char* JSON string, which varies with APIs.
    user_data Const void* User-defined data, which is passed through by the IM SDK without being processed.

    All the callbacks need to check whether the value of code is ERR_SUC. If not, the API failed to be called, and the specific cause of the failure is revealed by the parameters code and desc. For details, see Error Codes.

    For the following APIs, the TIMCommCallback parameter json_params is a "" null string:

    Example 1: JSON string of the TIMCommCallback parameter json_params for the API TIMSetConfig. For details on JSON keys, see SetConfig.

    {
       "set_config_callback_log_level" : 2,
       "set_config_is_log_output_console" : true,
       "set_config_log_level" : 2,
       "set_config_proxy_info" : {
          "proxy_info_ip" : "",
          "proxy_info_port" : 0
       },
       "set_config_user_config" : {
          "user_config_group_getinfo_option" : {
             "get_info_option_custom_array" : [],
             "get_info_option_info_flag" : 0xffffffff,
             "get_info_option_role_flag" : 0
          },
          "user_config_group_member_getinfo_option" : {
             "get_info_option_custom_array" : [],
             "get_info_option_info_flag" : 0xffffffff,
             "get_info_option_role_flag" : 0
          },
          "user_config_is_ingore_grouptips_unread" : false,
          "user_config_is_read_receipt" : false,
          "user_config_is_sync_report" : false
       }
    }

    Example 2: JSON string of the TIMCommCallback parameter json_params for the API TIMConvCreate. For details on JSON keys, see ConvInfo.

    {
       "conv_active_time" : 1551269275,
       "conv_id" : "user2",
       "conv_is_has_draft" : false,
       "conv_is_has_lastmsg" : true,
       "conv_last_msg" : {
          "message_client_time" : 1551101578,
          "message_conv_id" : "user2",
          "message_conv_type" : 1,
          "message_elem_array" : [
             {
                "elem_type" : 0,
                "text_elem_content" : "12"
             }
          ],
          "message_is_from_self" : false,
          "message_is_read" : true,
          "message_rand" : 3726251374,
          "message_sender" : "user2",
          "message_seq" : 56858,
          "message_server_time" : 1551101578,
          "message_status" : 2
       },
       "conv_owner" : "",
       "conv_type" : 1,
       "conv_unread_num" : 1
    }

    Example 3: JSON string of the TIMCommCallback parameter json_params for the API TIMConvGetConvList. For details on JSON keys, see ConvInfo.

    [
       {
          "conv_active_time" : 1551269275,
          "conv_id" : "user2",
          "conv_is_has_draft" : false,
          "conv_is_has_lastmsg" : true,
          "conv_last_msg" : {
             "message_client_time" : 1551235066,
             "message_conv_id" : "user2",
             "message_conv_type" : 1,
             "message_elem_array" : [
                {
                   "elem_type" : 0,
                   "text_elem_content" : "ccccccccccccccccc"
                }
             ],
             "message_is_from_self" : true,
             "message_is_read" : true,
             "message_rand" : 1073033786,
             "message_sender" : "user1",
             "message_seq" : 16373,
             "message_server_time" : 1551235067,
             "message_status" : 2
          },
          "conv_owner" : "",
          "conv_type" : 1,
          "conv_unread_num" : 0
       }
    ]

    Example 4: JSON string of the TIMCommCallback parameter json_params for the API TIMMsgSendNewMsg. For details on JSON keys, see Message.

    {
       "message_client_time" : 1558598732,
       "message_conv_id" : "asd12341",
       "message_conv_type" : 1,
       "message_custom_int" : 0,
       "message_custom_str" : "",
       "message_elem_array" : [
          {
             "elem_type" : 0,
             "text_elem_content" : "test"
          }
       ],
       "message_is_from_self" : true,
       "message_is_online_msg" : false,
       "message_is_peer_read" : false,
       "message_is_read" : true,
       "message_priority" : 1,
       "message_rand" : 1340036983,
       "message_sender" : "test_win_01",
       "message_seq" : 20447,
       "message_server_time" :