IM SDK Callbacks

Last updated: 2021-01-05 10:11:30

    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.

    Note:

    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.

    Note:

    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.

    Note:

    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.

    Note:


    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" : tru