Group APIs

Last updated: 2021-01-05 10:09:57

    For more information about groups, see Group system, Group Management, and Custom Fields.

    TIMGroupCreate

    This API is used to create a group.

    Prototype

    TIM_DECL int TIMGroupCreate(const char* json_group_create_param, TIMCommCallback cb, const void* user_data);

    Parameters

    Parameter Type Description
    json_group_create_param const char* JSON string of the API parameter for creating a group.
    cb TIMCommCallback Callback for notifying whether a group was created. For more information about the callback function definition and parameter parsing, see TIMCommCallback.
    user_data const void* User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

    Return values

    Type Description
    int If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

    Note:

    • You can specify a group ID when creating a group. If no group ID is specified, the IM CVM will generate a unique ID to facilitate subsequent operations. The callback set by this API returns the group ID.
    • For more information about JSON keys for creating group parameters, see CreateGroupParam.

    Example

    Json::Value json_group_member_array(Json::arrayValue);
    
    Json::Value json_value_param;
    json_value_param[kTIMCreateGroupParamGroupId] = "first group id";
    json_value_param[kTIMCreateGroupParamGroupType] = kTIMGroup_Public;
    json_value_param[kTIMCreateGroupParamGroupName] = "first group name";
    json_value_param[kTIMCreateGroupParamGroupMemberArray] = json_group_member_array;
    
    json_value_param[kTIMCreateGroupParamNotification] = "group notification";
    json_value_param[kTIMCreateGroupParamIntroduction] = "group introduction";
    json_value_param[kTIMCreateGroupParamFaceUrl] = "group face url";
    json_value_param[kTIMCreateGroupParamMaxMemberCount] = 2000;
    json_value_param[kTIMCreateGroupParamAddOption] = kTIMGroupAddOpt_Any;
    
    const void* user_data = nullptr; // Returned by the callback function
    int ret = TIMGroupCreate(json_value_param.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
       if (ERR_SUCC != code) { 
            // Failed to create a group.
            return;
        }
    
        // The group was created. Parse the JSON content to obtain GroupID of the created group.
    }, user_data);
    if (TIM_SUCC != ret) {
        // Failed to call the TIMGroupCreate API.
    }
    
    // The json_group_create_param JSON string obtained by json_value_param.toStyledString().c_str() is as follows:
    {
       "create_group_param_add_option" : 2,
       "create_group_param_face_url" : "group face url",
       "create_group_param_group_id" : "first group id",
       "create_group_param_group_member_array" : [],
       "create_group_param_group_name" : "first group name",
       "create_group_param_group_type" : 0,
       "create_group_param_introduction" : "group introduction",
       "create_group_param_max_member_num" : 2000,
       "create_group_param_notification" : "group notification"
    }

    TIMGroupDelete

    This API is used to delete or disband a group.

    Prototype

    TIM_DECL int TIMGroupDelete(const char* group_id, TIMCommCallback cb, const void* user_data);

    Parameters

    Parameter Type Description
    group_id const char* ID of the group to be deleted.
    cb TIMCommCallback Callback function for notifying whether the group was deleted. For more information about the callback function definition, see TIMCommCallback.
    user_data const void* User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

    Return values

    Type Description
    int If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.

    Note:

    • Permission description:
      • No one has the permission to disband a private group.
      • The group owner can disband a public group, chat room, or broadcasting chat room.
    • When this API is called to delete a group with the specified group_id, parameters of the callback function cb determine whether the group was deleted.

    TIMGroupJoin

    This API is used to apply to join a group.

    Prototype

    TIM_DECL int TIMGroupJoin(const char* group_id, const char* hello_msg, TIMCommCallback cb, const void* user_data);

    Parameters

    Parameter Type Description
    group_id const char* ID of the group to be joined.
    hello_msg const char* (Optional) Application reason.
    cb TIMCommCallback Callback for notifying whether joining a group was successful. For more information about the callback function definition, see TIMCommCallback.
    user_data const void* User-defined data. The IM SDK only transfers the user data to the callback function cb without processing the data.

    Return values

    Type Description
    int If TIM_SUCC is returned, the API was successfully called. (The callback cb is called only when the API returns TIM_SUCC.) If other values are returned, the API failed to be called. For more information about the definition of each return value, see TIMResult.