登录与登出

登录集成必读

手动登录

SDK 登录后会同步群信息,离线消息,漫游消息,系统通知等数据,所以首次登录前需要 提前注册所需的全局广播类通知的回调 (具体说明请参阅API 文档),以下以注册最近会话变更通知回调为例:

//全局会话列表变更通知函数
void CallbackSessionChange(int rescode, const char *result, int total_unread_counts, const char *json_extension, const void *user_data)
{
    if (rescode == kNIMResSuccess)
    {
        //处理会话变更
    }
    else
    {
        //错误处理
    }
}

void foo()
{
    //注册全局会话列表变更通知函数
    nim_session_reg_change_cb(NULL, &CallbackSessionChange, NULL);  // 会话列表变更通知(nim_session)
}

通过注册以下接口用来正确维护当前账号的状态:

// 帐号被踢通知(nim_client)
void nim_client_reg_kickout_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);
// 网络连接断开通知(nim_client)
void nim_client_reg_disconnect_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);
// 多端登录/登出通知
void nim_client_reg_multispot_login_notify_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);
/** @fn void nim_client_login(const char *app_key, const char *account, const char *token, const char *json_extension, nim_json_transport_cb_func cb, const void *user_data)
* NIM客户端登录,传入的JSON参数定义见nim_client_def.h    
* @param[in] app_key APP key
* @param[in] account APP account
* @param[in] token 令牌 (在后台绑定的登录token)
* @param[in] json_extension json扩展参数(备用,目前不需要)
* @param[in] cb 登录流程的回调函数, nim_json_transport_cb_func回调函数定义见nim_global_def.h
* @param[in] user_data APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
* @return void 无返回值
* @note 错误码    200:成功
*        302:账号或密码错误
*        403:禁止操作
*        408:请求超时
*        414:参数错误
*        415:网络连接出现错误
*        416:频率超限
*        422:账号被禁用
*        20002:账号已经处于登录状态
*/
NIM_SDK_DLL_API    void nim_client_login(const char *app_key, const char *account, const char *token, const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);
void CallbackLogin(const char* res, const void *user_data)
{
    //解析JSON数据处理登录状态
    json_value *value = fcx_null;
    int length = fcx_strlen(g_login_cb_json_params);
    value = json_parse(g_login_cb_json_params, length);
    if (value)
    {
        int code = json_value_find_as_int(value, "err_code");
        int step = json_value_find_as_int(value, "login_step");

        switch (step)
        {
        case kNIMLoginStepLinking:
            break;
        case kNIMLoginStepLogining:
            break;
        case kNIMLoginStepLogin:
            //登录鉴权结果
            break;
        default:
            FCX_DEBUG_ERROR("Unknown login step!");
            break;
        }
    }
    json_value_free(value);
}

void foo()
{
    //app key: 应用标识,不同应用之间的数据(用户,消息,群组等)是完全隔离的。开发自己的应用时,需要替换成自己申请来的app key
    //注意:替换成客户自己的app key之后,请不要对登录密码进行md5加密。
    nim_client_login("app key", "app account", "token", NULL, &CallbackLogin, NULL);
}

自动登录

SDK 在网络连接断开后,会监听网络状况,在网络可用时自动执行登录。SDK提供了网络断开和自动登录结果的回调,开发者可以注册这些回调获取结果,在回调函数中根据需要通知用户或者做其他处理。

注意: 自动重新登录的机制可能会失效:

如果重新登录回调函数返回的的错误号既不是kNIMResSuccess,也不是网络错误相关错误号(kNIMResTimeoutError或者kNIMResConnectionError),那么说明自动重新登录的机制已经失效,需要开发者退回到登录界面进行手动重新登录。

/** @fn nim_client_reg_disconnect_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data)
* (全局回调)注册NIM客户端掉线回调
* @param[in] json_extension json扩展参数(备用,目前不需要)
* @param[in] cb 掉线的回调函数, nim_json_transport_cb_func回调函数定义见nim_global_def.h
* @param[in] user_data APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
* @return void 无返回值
*/
NIM_SDK_DLL_API void nim_client_reg_disconnect_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);

/** @fn void nim_client_reg_auto_relogin_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data)
* (全局回调)注册NIM客户端自动重连回调。重连失败时,如果不是网络错误引起的(网络相关的错误号为kNIMResTimeoutError和kNIMResConnectionError),而是服务器返回了非kNIMResSuccess的错误号,
* 则说明重连的机制已经失效,需要APP层调用nim_client_logout执行注销操作并退回到登录界面后进行重新登录。
* @param[in] json_extension json扩展参数(备用,目前不需要)
* @param[in] cb 自动重连的回调函数, nim_json_transport_cb_func回调函数定义见nim_global_def.h。
*                  如果返回错误号kNIMResExist,说明无法继续重连,App层必须调用nim_client_logout退出到登录界面,以便用户重新进行登录。
* @param[in] user_data APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
* @return void 无返回值
* @note 错误码    200:成功
*                403:禁止操作
*                408:请求超时
*                414:参数错误
*                415:网络连接出现错误
*                416:频率超限
*                422:账号被禁用
*/
NIM_SDK_DLL_API    void nim_client_reg_auto_relogin_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);

登出

应用层登出/注销自己的账号时需要调用 SDK 的登出操作nim_client_logout, 该操作会通知云信服务器进行 APNS 推送信息的解绑操作,避免用户已登出但推送依然发送到当前设备的情况发生。在调用 Logout 时需要设置正确的 NIMLogoutType 参数。如果需要调用nim_client_cleanup,必须在完全退出(收到退出回调)后执行。

/** @fn void nim_client_logout(enum NIMLogoutType logout_type, const char *json_extension, nim_json_transport_cb_func cb, const void *user_data)
* NIM客户端注销/退出,传入的JSON参数定义见nim_client_def.h 
* @param[in] logout_type Logout操作类型,其定义见nim_client_def.h
* @param[in] json_extension json扩展参数(备用,目前不需要)
* @param[in] cb 注销/退出的回调函数, nim_json_transport_cb_func回调函数定义见nim_global_def.h
* @param[in] user_data APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
* @return void 无返回值
* @note 错误码    200:成功
*        500:未知错误
*/
NIM_SDK_DLL_API    void nim_client_logout(enum NIMLogoutType logout_type, const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);
void CallbackLogout(const char* res, const void *user_data)
{
    //nim_client_logout执行完成,可以安全调用nim_client_cleanup
}

void foo()
{
    nim_client_logout(kNIMLogoutAppExit, NULL, &CallbackLogout, NULL);
}

多端登录

通过调用nim_client_reg_multispot_login_notify_cb来注册多端登录通知的回调函数,当用户在某个客户端登录时,其他没有被踢掉的端会触发这个回调函数,并携带当前时间登录的设备列表的数据。登录时如果有其他端也处于登录状态,在登录回调函数中也包含这些设备的信息。

/** @fn void nim_client_reg_multispot_login_notify_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data)
* (全局回调)注册NIM客户端多点登录通知回调
* @param[in] json_extension json扩展参数(备用,目前不需要)
* @param[in] cb 多点登录通知的回调函数, nim_json_transport_cb_func回调函数定义见nim_global_def.h
* @param[in] user_data APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
* @return void 无返回值
*/
NIM_SDK_DLL_API void nim_client_reg_multispot_login_notify_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);
static void CallbackMutliSpotLogin(const char* json_res, const void* user_data)
{
    Json::Reader reader;
    Json::Value values;
    if (json_res != nullptr && reader.parse((std::string)json_res, values) && values.isObject())
    {
        //获取多端登录设备信息
    }
}

typedef void(*nim_client_reg_multispot_login_notify_cb)(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);

void foo()
{
    nim_client_reg_multispot_login_notify_cb func = (nim_client_reg_multispot_login_notify_cb) GetProcAddress(hInst, "nim_client_reg_multispot_login_notify_cb");
    func(nullptr, &CallbackMutliSpotLogin, nullptr);
}

互踢

网易云通信内置踢人策略为:移动端(Android,iOS)互踢,桌面端(PC,Web)互踢,移动端和桌面端共存。通过接口nim_client_reg_kickout_cb来注册被踢出回调函数,当收到此通知时,一般是退出程序然后回到登录窗口,回调函数参数中详细说明了被踢出的原因。

如果当前的互踢策略无法满足业务需求的话,可以联系我们取消内置互踢,根据多端登录的回调和当前的设备列表,判断本设备是否需要被踢出。如果需要踢出,直接调用登出接口并在界面上给出相关提示即可。

/** @fn void nim_client_reg_kickout_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data)
* (全局回调)注册NIM客户端被踢回调
* @param[in] json_extension json扩展参数(备用,目前不需要)
* @param[in] cb 被踢的回调函数, nim_json_transport_cb_func回调函数定义见nim_global_def.h
* @param[in] user_data APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
* @return void 无返回值
*/
NIM_SDK_DLL_API void nim_client_reg_kickout_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);
void CallbackKickout(const char* res, const void* user_data)
{
    //解析res
}

typedef void(*nim_client_reg_kickout_cb)(const char *json_extension, nim_json_transport_cb_func cb, const void* user_data);

void foo()
{
    nim_client_reg_kickout_cb func = (nim_client_reg_kickout_cb) GetProcAddress(hInst, "nim_client_reg_kickout_cb");
    func(nullptr, &CallbackKickout, nullptr);
}

获取登录状态

开发者通过调用nim_client_get_login_state主动获取当前用户在线状态。

/** @fn int nim_client_get_login_state(const char *json_extension)
* 获取NIM客户端登录状态
* @param[in] json_extension json扩展参数(备用,目前不需要)
* @return int 1:已登录 2:未登录
*/
NIM_SDK_DLL_API int nim_client_get_login_state(const char *json_extension)