登录登出 - IM 即时通讯

IM 即时通讯

开发指南

圈组功能

更新时间： 2022/11/30 14:38:42

C++

static void SetProxy(NIMProxyType type, const std::string& host, int port, const std::string& user, const std::string& password);

File:nim_cpp_global.h

Namespace:NIM

Class：Global
C#

static void SetProxy (NIMProxyType type, string host, int port, string user, string password);

Namespace:NIM

Class：GlobalAPI
C

NIM_SDK_DLL_API void nim_global_set_proxy(enum NIMProxyType type, const char *host, int port, const char *user, const char *password);

File:nim_global.h

参数说明

参数	类型	必须	说明
type	enum	是	代理类型，见NIMProxyType定义, 其中音视频和白板暂时只支持kNIMProxySocks5代理
host	string	是	代理地址
port	int	是	代理端口
user	string	否	代理用户名
password	string	否	代理密码

示例

void foo()
{
	nim::Global::SetProxy(nim::kNIMProxySocks5, "123.123.123.123", "400", "test", "test");
}

void foo()
{
	NIM.GlobalAPI.SetProxy(NIM.NIMProxyType.kNIMProxySocks5, "123.123.123.123", "400", "test", "test");
}

typedef void(*nim_global_set_proxy)(NIMProxyType, const char*, int, const char*, const char*);
void foo()
{
	nim_global_set_proxy func = (nim_global_set_proxy) GetProcAddress(hInst, "nim_global_set_proxy");
	func(kNIMProxySocks5, "123.123.123.123", "400", "test", "test");
}

手动登录

SDK 登录后会同步群信息，离线消息，漫游消息，系统通知等数据，所以首次登录前需要 提前注册好全局广播类通知的回调 （具体说明请查看前章接口介绍或参阅API 文档）。

API介绍

C++

static bool Login (const std::string &app_key, const std::string &account, const std::string &password, const LoginCallback &cb, const std::string &json_extension="")

File:nim_cpp_client.h

Namespace:NIM

Class：Client
C#

static void Login (string appKey, string account, string token, LoginResultDelegate handler=null)

Namespace:NIM

Class：ClientAPI
C

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)

File:nim_client.h

参数说明

参数	类型	必须	说明
app_key/appKey	string	是	注册的云信APP KEY
account	string	是	账号
password/token	string	是	密码
cb/handler	function	是	登录流程的回调函数
json_extension(C/C++)	string	否	json扩展参数(备用，目前不需要)
user_data(C)	void*	否	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void OnLoginCallback(const nim::LoginRes& login_res)
{
	if (login_res.res_code_ == nim::kNIMResSuccess)
	{
		if (login_res.login_step_ == nim::kNIMLoginStepLogin)
		{
			···
		}
	}
	else
	{
		···
	}
}

void foo()
{
	nim::Client::Login(app_key, "app account", "token", &OnLoginCallback);
}

private void HandleLoginResult(NIM.NIMLoginResult result)
{
	//在UI线程进行处理登录结果
	Action action = () =>
	{
		if (result.LoginStep == NIM.NIMLoginStep.kNIMLoginStepLogin)
		{
			if (result.Code == NIM.ResponseCode.kNIMResSuccess)
			{
				//TODO：登录成功
			}
			else
			{
				//TODO:登录失败
			}
		}
	};
	this.Invoke(action);
}

private void foo()
{
	NIM.ClientAPI.Login(appkey, "app account", "token", HandleLoginResult);
}

void CallbackLogin(const char* res, const void *user_data)
{
	Json::Value values;
	Json::Reader reader;
	if (reader.parse(res, values) && values.isObject())
	{
		if (values[kNIMLoginStep].asInt() == kNIMLoginStepLogin && values[kNIMErrorCode].asInt() == 200)
		{
			...
		}
		...
	}
}

typedef	void(*nim_client_login)(const char *app_key, const char *account, const char *password, const char *json_extension, nim_json_transport_cb_func cb, const void* user_data);

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

在回调函数 nim_json_transport_cb_func 中，判断 json_params：其中 NIMLoginStep 的枚举值为 kNIMLoginStepLogin = 3 并且 kNIMErrorCode 为 kNIMResSuccess = 200 表示登录成功。

自动登录

SDK 在网络连接断开后，会监听网络状况，开发者可以通过注册连接断开广播通知，在通知的回调函数中开发者只要根据需要打印log或通知用户即可。

C++

static void RegDisconnectCb (const DisconnectCallback &cb, const std::string &json_extension="")

File:nim_cpp_client.h

Namespace:NIM

Class：Client

示例：
```
  void OnDisconnectCallback()
  {
  	···
  }
  
  void foo()
  {
  	nim::Client::RegDisconnectCb(&OnDisconnectCallback);
  }
```

static void RegDisconnectedCb (Action handler)

Namespace:NIM

Class：ClientAPI

示例：

  private foo()
  {
  	NIM.ClientAPI.RegDisconnectedCb(() =>
  	{
  	 	MessageBox.Show("网络连接断开，网络恢复后后会自动重连");
  	});
  }

NIM_SDK_DLL_API void nim_client_reg_disconnect_cb (const char *json_extension, nim_json_transport_cb_func cb, const void *user_data)

File:nim_client.h

示例：

  void CallbackDisconnect(const char* res, const void* user_data)
  {
  	//解析res
  }

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

  void foo()
  {
  	nim_client_reg_disconnect_cb func = (nim_client_reg_disconnect_cb) GetProcAddress(hInst, "nim_client_reg_disconnect_cb");
  	func(nullptr, &CallbackDisconnect, nullptr);
  }

如果网络状况好转，那么SDK 会自动进行重新登录，登录结果可以在注册的重新登录回调函数中处理。

注意自动重新登录的机制可能会在以下场景中失效：

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

SDK 在重新登录失效后，可以由用户手动调用重新登录接口。

c++

static void Relogin (const std::string &json_extension="")

File:nim_cpp_client.h

Namespace:NIM

Class：Client
c#

static void NIM.ClientAPI.Relogin(string jsonExtension = null)

Namespace:NIM

Class：ClientAPI
c

NIM_SDK_DLL_API void nim_client_relogin (const char *json_extension)

File:nim_client.h

登出

执行接口nim_client_logout 进行登出或退出，登出或退出的过程因为涉及到和服务器的交互以及需要将缓存中的数据持久化到本地，因此根据实际情况回调通知会有1s到20s左右的延迟。清理SDK必须在完全退出（收到退出回调）后执行。

**Trick:**因为退出和其他接口一样，总是在某些情况下会出现未及时返回需要上层界面等待的情况(比如网络原因导致服务器返回慢甚至超时，缓存数据大持久化到本地慢等原因)，因此开发者可以通过暂时隐藏UI，让进程等待退出完成的回调后再执行清理SDK，退出程序的工作。

API介绍

C++

static void Logout (NIMLogoutType logout_type, const LogoutCallback &cb, const std::string &json_extension="")

File:nim_cpp_client.h

Namespace:NIM

Class：Client
C#

static void Logout (NIMLogoutType logoutType, LogoutResultDelegate @delegate)

Namespace:NIM

Class：ClientAPI
C

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)

File:nim_client.h

参数说明

参数	类型	必须	说明
logout_type/logoutType	enum	是	Logout类型，见NIMLogoutType
cb/delegate	function	是	注销/退出的回调函数
json_extension(C/C++)	string	否	json扩展参数(备用，目前不需要)
user_data(C)	void*	否	APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理

示例

void LoginCallback::OnLogoutCallback(nim::NIMResCode res_code)
{
	//如果是退出程序
	nim::Client::Cleanup();
	...

	//如果是登出到登录界面，这里不能执行清理SDK工作，否则会报错
	...
}

void foo()
{
	//登出到登录界面(nim::kNIMLogoutChangeAccout) 或者 退出程序(nim::kNIMLogoutAppExit)
	nim::Client::Logout(nim::kNIMLogoutAppExit, &OnLogoutCallback);
}

void foo()
{
	System.Threading.Semaphore s = new System.Threading.Semaphore(0, 1);
	NIM.ClientAPI.Logout(NIM.NIMLogoutType.kNIMLogoutAppExit, (r) =>
	{
		s.Release();
	});
	//需要logout执行完才能退出程序
	s.WaitOne(TimeSpan.FromSeconds(10));
	NIM.ClientAPI.Cleanup();
}

void CallbackLogout(const char* res, const void *user_data)
{
	...
}

typedef	void(*nim_client_logout)(nim::NIMLogoutType logout_type, const char *json_extension, nim_json_transport_cb_func cb, const void* user_data);

void foo()
{
	nim_client_logout func = (nim_client_logout) GetProcAddress(hInst, "nim_client_logout");
	func(kNIMLogoutAppExit, nullptr, &CallbackLogout, nullptr);
}

多端登录和互踢

通过提前注册全局的多端登录广播通知，当用户在某个客户端登录时，其他没有被踢掉的端会触发这个通知的回调函数，并携带当前时间登录的设备列表的数据。

通过提前注册全局的被踢出广播通知，当收到此通知时，一般是退出程序然后回到登录窗口，回调函数参数中详细说明了被踢出的原因。

当前云信SDK支持配置四种不同的 IM 多端登录策略：

只允许一端登录，Windows、Web、Android、iOS 彼此互踢
桌面PC 与 Web 端互踢、移动 Android 和 iOS 端互踢、桌面与移动端可同时登录
- 如果SDK相同，互踢
- Windows SDK和Web SDK为一类，Android SDK和iOS SDK为另一类，这两类之间，同类互踢，不同类不互踢
各端均可以同时登录在线（最多10个设备同时在线）
自定义多端登录配置

具体的如何配置，请参见多端登录与互踢策略。

如果当前的互踢策略无法满足业务需求的话，可以联系销售或技术支持取消内置互踢，根据多端登录的回调和当前的设备列表，判断本设备是否需要被踢出。如果需要被踢出，直接调用登出接口并在界面上给出相关提示即可；同样的也可以根据需要踢出在其他端登陆的账号。

API介绍

注册多端登陆广播

注意：聊天室多端登录相关的通知不是通过这个接口监听的，具体请看下文聊天室开发说明。
- C++
  
  static void RegMultispotLoginCb (const MultiSpotLoginCallback &cb, const std::string &json_extension="")
  
  File:nim_cpp_client.h
  
  Namespace:NIM
  
  Class：Client
- C#
  
  static void RegMultiSpotLoginNotifyCb (MultiSpotLoginNotifyResultHandler handler)
  
  Namespace:NIM
  
  Class：ClientAPI
- C
  
  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)
  
  File:nim_client.h
注册被踢广播

注意：聊天室被踢出通知不是通过这个接口监听的，具体请看下文聊天室开发说明。
- C++
  
  static void RegKickoutCb (const KickoutCallback &cb, const std::string &json_extension="")
  
  File:nim_cpp_client.h
  
  Namespace:NIM
  
  Class：Client
- C#
  
  static void RegKickoutCb (KickoutResultHandler handler)
  
  Namespace:NIM
  
  Class：ClientAPI
- C
  
  NIM_SDK_DLL_API void nim_client_reg_kickout_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data)
  
  File:nim_client.h

示例

注册多端登陆广播

回调函数中包含其他端的在线状态列表，返回客户端类型、操作系统、登录时间，设备 MAC 地址等信息。

如果设备 ID 相同，例如异常登出后马上重新登录、同一台设备上的多实例等情况，收到的回调将不包含设备信息。

void LoginCallback::OnMultispotLoginCallback(const nim::MultiSpotLoginRes& res)
{
	...
}
nim::Client::RegMultispotLoginCb(&nim_comp::LoginCallback::OnMultispotLoginCallback);

//注册多端登录通知回调
NIM.ClientAPI.RegMultiSpotLoginNotifyCb(OnMultiSpotLogin);

//result 包含多端登录的其他端信息
private static void OnMultiSpotLogin(NIMMultiSpotLoginNotifyResult result)
{
	
}

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);
}

注册被踢广播
C++

void OnKickoutCallback(const nim::KickoutRes& res)
{
	···
}

void foo()
{
	nim::Client::RegKickoutCb(&OnKickoutCallback);
}

private foo()
{
	NIM.ClientAPI.RegKickoutCb((r) =>
	{
		MessageBox.Show(r.Dump(), "被踢下线，请注意账号安全");
	});
}

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);
}

其中，kNIMKickoutReasonCode 表示被踢原因，kNIMKickoutClientType 表示发起踢出的客户端类型。

动态登录

动态 token 策略下，登录凭据具备时效性，过期即失效。可以有效降低token泄露造成的影响，提升登录安全性。
nim::Client::Login接口的参数 "json_extension" 传入LoginParams,LoginParams可通过调用 nim::Client::LoginCustomDataToJson接口转换为 string 类型.
如果使用的是nim::NIMAuthType::kNIMAuthTypeByAppToken(第三方回调的token方式),需要在登录前使用RegReloginRequestToeknCb向sdk注册登录时获取新的token回调方法(nim::Client::ReloginRequestTokenCallback),当SDK需要获取登录token时会进行回调

enum NIMAuthType {
	kNIMAuthTypeDefault,        /**< 默认登录方式 */  
	kNIMAuthTypeBySecretToken,  /**< 使用 App secret 生成的 token */  
	kNIMAuthTypeByAppToken,     /**< 使用第三方回调服务器生成的 token */  
};

此文档是否对你有帮助？

有帮助

我要吐槽