准备工作：将SDK 相关的dll 文件（nim.dll，nim_audio.dll, nim_tools_http.dll, nrtc.dll）放到App 的运行目录下，并将SDK 的配置文件目录nim_conf（目录里包含一个ver_ctrl.dll文件）放到App 的运行目录下。SDK 基于vs2013+vs2017 开发，如果App 没有对应的运行时库文件，请将redist_packages文件夹中动态库及msvcp120.dll和msvcr120.dll放到App 的运行目录下。

准备工作完成后，在程序启动时，如果直接使用C接口，需要调用LoadLibrary 函数动态加载nim.dll，然后调用GetProcAddress获取API 接口：nim_client_init，调用此接口初始化NIM SDK。同时，SDK 能力的一些参数以及如果SDK 需要连接独立部署的服务器的地址等配置也是在初始化SDK 时传入。

API 介绍

• C++

  static bool Init (const std::string &app_key, const std::string &app_data_dir, const std::string &app_install_dir, const SDKConfig &config)

  File:nim_cpp_client.h

  Namespace:NIM

  Class：Client

• C#

  static bool Init (string appDataDir, string appInstallDir="", NimUtility.NimConfig config=null)

  Namespace:NIM

  Class：ClientAPI

• C

  NIM_SDK_DLL_API bool nim_client_init (const char *app_data_dir, const char *app_install_dir, const char *json_extension)

  File:nim_client.h

参数说明

• C/C++

参数	类型	必须	说明
app_key(C++)	std::string	是	应用注册的云信APP KEY
app_data_dir	std::string	是	使用默认路径时只需传入单个目录名(不以反斜杠结尾)， 使用自定义路径时需传入完整路径(以反斜杠结尾， 并确保有正确的读写权限！)
app_install_dir	std::string	否	SDK动态库所在的目录全路径(如果传入为空， 则按照默认规则搜索该动态库)
config(C++)	struct	否	初始化特殊参数(下文会作说明)
json_extension(C)	std::string	否	初始化特殊参数(下文会作说明)

• C#

参数	类型	必须	说明
appDataDir	std::string	是	使用默认路径时只需传入单个目录名(不以反斜杠结尾)， 使用自定义路径时需传入完整路径(以反斜杠结尾，并确保有正确的读写权限！)
appInstallDir	std::string	否	SDK动态库所在的目录全路径(如果传入为空， 则按照默认规则搜索该动态库)
config	struct	否	初始化特殊参数(下文会作说明)

初始化特殊参数说明

初始化时开发者可以通过设置SDKConfig(C++)/NIMConfig(C#)/json_extenstion(C)来设置特殊参数。

• C++

SDKConfig参数	类型	说明
database_encrypt_key_	std::string	数据库秘钥，建议必填，目前只支持最多32个字符的加密密钥！ 建议使用32个字符
custom_timeout_	int	通讯自定义超时时间,暂时不开放设置
login_max_retry_times_	int	登录重试最大次数，如需设置建议设置大于3次，SDK默认设置次数
preload_attach_	bool	是否需要预下载附件(图片和语音),选填,默认为true, 如果有对带宽流量有较高要求的请关闭该选项，改为上层开发者按需下载附件文件
preload_image_quality_	int	预下载图片质量,选填,范围0-100
preload_image_resize_	std::string	预下载图片基于长宽做内缩略,选填,比如宽100高50,则赋值为100x50,中间为字母小写x
preload_image_name_template	std::string	IM消息附件（图片、视频封面）缩略图命名规则，以{filename}为token进行替换
sdk_log_level_	enum	SDK log级别,定义见NIMSDKLogLevel，选填，SDK默认的内置级别为kNIMSDKLogLevelPro
sync_session_ack_	bool	设置是否已读未读状态多端同步，默认true
reset_unread_count_when_recall	bool	撤回消息是否重新计算未读消息计数，默认为false
use_https	bool	是否启用HTTPS协议，默认为true, 如果是私有服务器且启用https那私有化，需要配置nos_uploader_host
use_private_server_	bool	是否使用私有服务器，如果使用私有服务器，则必须设置为true
default_link_address_	std::list< std::string>	默认link服务器地址，如果选择使用私有服务器，则必填
default_nos_access_address_	std::list< std::string>	默认nos access服务器地址， 如果选择使用私有服务器，则必填
default_nos_download_address_	std::list< std::string>	默认nos 下载服务器地址， 如果选择使用私有服务器，则必填
default_nos_upload_address_	std::list< std::string>	默认nos 上传服务器地址， 如果选择使用私有服务器，则必填
lbs_address_	std::string	lbs地址，如果选择使用私有服务器，则必填
nos_lbs_address_	std::string	nos lbs地址，如果选择使用私有服务器，则必填
rsa_public_key_module_	std::string	RSA public key，如果选择使用私有服务器，则必填
rsa_version_	int	RSA version，如果选择使用私有服务器，则必填
nos_download_address_list_	std::vector< std::string >	nos 下载地址拼接模板，用于拼接最终得到的下载地址
nos_accelerate_host_list_	std::vector< std::string >	需要被加速主机名
nos_accelerate_address_list_	std::vector< std::string >	nos 加速地址拼接模板，用于获得加速后的下载地址
ntserver_address_list_	std::vector< std::string >	部分 IM 错误信息统计上报地址
upload_statistics_data_	bool	错误信息统计是否上报,私有化如不上报此项应配置为false
caching_markread_enabled	bool	配置SDK是否开启批量向服务端发送“已接收回执”功能，程序可能收到大量消息以至触发频控时可以考虑开启此开关 缺省 false
caching_markread_time	int	caching_markread_enabled == true 时有效 缓存时间 单位ms 缺省 1000
caching_markread_count	int	caching_markread_enabled == true 时有效 缓存的最大消息条数 缺省 10
enable_user_datafile_backup	bool	是否开启用户数据备份(本地)功能 缺省true
enable_user_datafile_restore	bool	是否开启用户数据恢复(本地)功能 缺省false
enable_user_datafile_defrestoreproc	bool	是否使用缺省的用户数据恢复(本地)方案 缺省false, enable_user_datafile_restore == true 生效
user_datafile_localbackup_folder	std::string	用户数据文件备份（本地）目录,需保证有读写权限，缺省在数据文件所在目录创建一个db_file.back目录

• C#

NIMConfig参数	类型	说明
AppKey	std::string	应用注册的云信APP KEY
CommonSetting.DataBaseEncryptKey	std::string	数据库秘钥，建议必填，目前只支持最多32个字符的加密密钥！ 建议使用32个字符
CommonSetting.PredownloadAttachmentThumbnail	bool	是否需要预下载附件(图片和语音),选填,默认为true, 如果有对带宽流量有较高要求的请关闭该选项，改为上层开发者按需下载附件文件
CommonSetting.LogLevel	enum	SDK log级别,定义见NIMSDKLogLevel，选填，SDK默认的内置级别为kNIMSDKLogLevelPro
CommonSetting.UsePriviteServer	bool	是否使用私有服务器，如果使用私有服务器，则必须设置为true
SdkPrivateServerSetting.LinkServerList	std::list< std::string>	默认link服务器地址，如果选择使用私有服务器，则必填
SdkPrivateServerSetting.AccessServerList	std::list< std::string>	默认nos access服务器地址，如果选择使用私有服务器，则必填
SdkPrivateServerSetting.DownloadServerList	std::list< std::string>	默认nos 下载服务器地址，如果选择使用私有服务器，则必填
SdkPrivateServerSetting.UploadServerList	std::list< std::string>	默认nos 上传服务器地址，如果选择使用私有服务器，则必填
SdkPrivateServerSetting.LbsAddress	std::string	lbs地址，如果选择使用私有服务器，则必填
SdkPrivateServerSetting.NOSLbsAddress	std::string	nos lbs地址，如果选择使用私有服务器，则必填
SdkPrivateServerSetting.RSAPublicKey	std::string	RSA public key，如果选择使用私有服务器，则必填
SdkPrivateServerSetting.RsaVersion	int	RSA version，如果选择使用私有服务器，则必填

• C

  C接口中，特殊参数是通过管理和设置一组json数据结构然后序列化为字符串(json_extension)后传入给SDK的，键的定义在nim_client_def.h头文件中。

键常量名	键常量值	值类型	说明
kNIMAppKey	app_key	std::string	应用注册的云信APP KEY
kNIMGlobalConfig	global_config	json object	常用配置，以下常用配置皆为该对象的子对象
kNIMDataBaseEncryptKey	db_encrypt_key	std::string	常用配置之一，数据库秘钥，建议必填， 目前只支持最多32个字符的加密密钥！建议使用32个字符
kNIMLoginRetryMaxTimes	login_max_retry_times	int	常用配置之一，登录重试最大次数， 如需设置建议设置大于3次，SDK默认设置次数
kNIMPreloadAttach	preload_attach	bool	常用配置之一，是否需要预下载附件(图片和语音),选填,默认为true, 如果有对带宽流量有较高要求的请关闭该选项，改为上层开发者按需下载附件文件
kNIMPreloadImageQuality	preload_image_quality	int	常用配置之一，预下载图片质量,选填,范围0-100
kNIMPreloadImageResize	preload_image_resize	std::string	常用配置之一，预下载图片基于长宽做内缩略,选填, 比如宽100高50,则赋值为100x50,中间为字母小写x
kPreloadAttachImageNameTemplate	preload_image_name_template	std::string	IM消息附件（图片、视频封面）缩略图命名规则，以{filename}为token进行替换
kNIMSDKLogLevel	sdk_log_level	enum	常用配置之一，SDK log级别,定义见NIMSDKLogLevel，选填，SDK默认的内置级别为kNIMSDKLogLevelPro
kNIMSyncSessionAck	sync_session_ack	bool	常用配置之一，设置是否已读未读状态多端同步，默认true
kNIMResetUnreadCountWhenRecall	reset_unread_count_when_recall	bool	撤回消息是否重新计算未读消息计数，默认为false
kNIMUseHttps	use_https	bool	是否启用HTTPS协议，默认为true, 如果是私有服务器且启用https那私有化，需要配置nos_uploader_host
kNIMPrivateServerSetting	private_server_setting	json object	私有服务器配置，以下常用私有服务器配置皆为该对象的子对象
kNIMDefaultLinkAddress	default_link	json string array	私有服务器配置之一，默认link服务器地址， 如果选择使用私有服务器，则必填
kNIMDefaultNosAccessAddress	default_nos_access	json string array	私有服务器配置之一，默认nos access服务器地址， 如果选择使用私有服务器，则必填
kNIMDefaultNosDownloadAddress	default_nos_download	json string array	私有服务器配置之一，默认nos 下载服务器地址， 如果选择使用私有服务器，则必填
kNIMDefaultNosUploadAddress	default_nos_upload	json string array	私有服务器配置之一，默认nos 上传服务器地址， 如果选择使用私有服务器，则必填
kNIMLbsAddress	lbs	std::string	私有服务器配置之一，lbs地址，如果选择使用私有服务器，则必填
kNIMNosLbsAddress	nos_lbs	std::string	私有服务器配置之一，nos lbs地址，如果选择使用私有服务器，则必填
kNIMRsaPublicKeyModule	rsa_public_key_module	std::string	私有服务器配置之一，RSA public key，如果选择使用私有服务器，则必填
kNIMRsaVersion	rsa_version	int	私有服务器配置之一，RSA version，如果选择使用私有服务器，则必填
kNIMDownloadAddressTemplate	download_address_template	json string array	nos 下载地址拼接模板，用于拼接最终得到的下载地址
kNIMAccelerateHost	accelerate_host	json string array	需要被加速主机名
kNIMAccelerateAddressTemplate	accelerate_address_template	json string array	nos 加速地址拼接模板，用于获得加速后的下载地址
kNIMNtserverAddress	ntserver_address	json string array	部分 IM 错误信息统计上报地址
kNIMUploadStatisticsData	is_upload_statistics_data	bool	错误信息统计是否上报,私有化如不上报此项应配置为false
kCachingMarkreadEnabled	caching_markread_enabled	bool	配置SDK是否开启批量向服务端发送“已接收回执”功能，程序可能收到大量消息以至触发频控时可以考虑开启此开关 缺省 false
kCachingMarkreadTime	caching_markread_time	int	caching_markread_enabled == true 时有效 缓存时间 单位ms 缺省 1000
kCachingMarkreadCount	caching_markread_count	int	caching_markread_enabled == true 时有效 缓存的最大消息条数 缺省 10
kEnableUserDataFileLocalBackup	enable_user_datafile_backup	bool	是否开启用户数据备份(本地)功能 缺省true
kEnableUserDataFileLocalRestore	enable_user_datafile_restore	bool	是否开启用户数据恢复(本地)功能 缺省false
kEnableUserDataFileDefRestoreProc	enable_user_datafile_defrestoreproc	bool	是否使用缺省的用户数据恢复(本地)方案 缺省false, enable_user_datafile_restore == true 生效
kUserDataFileLocalBackupFolder	user_datafile_localbackup_folder	std::string	用户数据文件备份（本地）目录,需保证有读写权限，缺省在数据文件所在目录创建一个db_file.back目录

启用HTTPS

通过设置初始化特殊参数可以启用HTTPS协议，具体可查阅参数说明列表。

示例

• C++

  nim::SDKConfig config;
  
  //组装SDK能力参数（必填）
  config.database_encrypt_key_ = "Netease";	 //string（db key必填，目前只支持最多32个字符的加密密钥！建议使用32个字符）
  config.sdk_log_level_ = 0;					 //bool 选填，是否需要预下载附件(图片和语音)，SDK默认预下载，如果有对带宽流量有较高要求的请关闭该选项，改为上层开发者按需下载附件文件
  config.preload_image_quality_ = 0;			 //int 预下载图片质量,选填,范围0-100
  config.preload_image_resize_ = "100x50";			 //string 预下载图片基于长宽做内缩略,选填,比如宽100高50,则赋值为100x50,中间为字母小写x
  config.sync_session_ack_ = true;			 //bool 选填，消息已读未读是否多端同步，默认true
  config.login_max_retry_times_ = 0;			 //int 登录重试最大次数，如需设置建议设置大于3次，默认填0，SDK默认设置次数
  
  //组装SDK独立部署的服务器配置（选填）
  config.use_private_server_ = true;
  config.rsa_public_key_module_ = "http://xxx";
  config.default_nos_download_address_.push_back("http://xxx.xxx.xxx.xxx:xxxx");
  config.lbs_address_ = "http://xxx";
  config.nos_lbs_address_ = "http://xxx";
  config.default_link_address_.push_back("http://xxx.xxx.xxx.xxx:xxxx");
  config.default_nos_upload_address_.push_back("http://xxx.xxx.xxx.xxx:xxxx");
  config.default_nos_access_address_.push_back("http://xxx.xxx.xxx.xxx:xxxx");
  
  // 载入网易云通信sdk，初始化安装目录和用户目录，第一个参数是appkey（此处填写的是测试示例）
  bool ret = nim::Client::Init("45c6af3c98409b18a84451215d0bdd6e", "Netease", "", config); 
  

• C#

  C# 程序在运行时需要使用到 C++ SDK 的dll，必须将SDK相关的dll 文件（nim.dll，nim_audio.dll, nim_tools_http.dll, nrtc.dll）放到最终的生成文件目录，如果缺少运行时库文件（msvcp100.dll和msvcr100.dll）也需要拷贝到生成目录中，否则可能会出现找不到dll的异常。

  C# 提供了参数配置类 NimUtility.NimConfig,通过创建该类对象完成参数配置。

  var config = new NimUtility.NimConfig();
  config.CommonSetting = new SdkCommonSetting();
  
  //组装SDK能力参数
  config.CommonSetting.DataBaseEncryptKey = "Netease"; //string（db key必填，目前只支持最多32个字符的加密密钥！建议使用32个字符）
  config.CommonSetting.LogLevel = SdkLogLevel.Pro;  //SDK 日志记录级别 
  config.CommonSetting.PredownloadAttachmentThumbnail = True;   //bool 选填，是否需要预下载附件(图片和语音)，SDK默认预下载，如果有对带宽流量有较高要求的请关闭该选项，改为上层开发者按需下载附件文件
  config.CommonSetting.UsePriviteServer = False;    //是否使用自定义服务器,默认False,如果使用自定义服务器，需设置config.PrivateServerSetting 对象
  
  //组装SDK独立部署的服务器配置
  config.PrivateServerSetting = new SdkPrivateServerSetting();
  config.PrivateServerSetting.RSAPublicKey = "http://xxx";
  config.PrivateServerSetting.DownloadServerList = new List<string>({"",""});
  config.PrivateServerSetting.LbsAddress = "http://xxx";
  config.PrivateServerSetting.NOSLbsAddress = "http://xxx";
  config.PrivateServerSetting.LinkServerList = new List<string>({"",""});
  config.PrivateServerSetting.UploadServerList = new List<string>({"",""});
  config.PrivateServerSetting.AccessServerList = new List<string>({"",""});
  
  bool ret = NIM.ClientAPI.Init("45c6af3c98409b18a84451215d0bdd6e", "NIMCSharpDemo", null, config); // 载入网易云通信sdk，初始化安装目录和用户目录，第一个参数是appkey（此处填写的是测试示例）
  

• C

  typedef bool(*nim_client_init)(const char *app_data_dir, const char *app_install_dir, const char *json_extension);
  
  void foo()
  {
  	//获取SDK初始化接口
  	HINSTANCE hInst = LoadLibraryW(L"nim.dll");
  	nim_client_init func = (nim_client_init) GetProcAddress(hInst, "nim_client_init");
  
  	//组装SDK初始化参数
  	Json::Value config_root;
  
  	//组装SDK能力参数（必填）
  	Json::Value config_values;
  	config_values[kNIMAppKey] = "xxxx"; //用户的APP key
  	config_values[kNIMDataBaseEncryptKey] = ""; //string（db key必填，目前只支持最多32个字符的加密密钥！建议使用32个字符）
  	config_values[kNIMPreloadAttach] = ;		//bool 选填，是否需要预下载附件(图片和语音)，SDK默认预下载，如果有对带宽流量有较高要求的请关闭该选项，改为上层开发者按需下载附件文件
  	config_values[kNIMPreloadImageQuality] = ;  //int 预下载图片质量,选填,范围0-100
  	config_values[kNIMPreloadImageResize] = ;   //string 预下载图片基于长宽做内缩略,选填,比如宽100高50,则赋值为100x50,中间为字母小写x
  	config_values[nim::kNIMSyncSessionAck] = ;			//bool 选填，消息已读未读是否多端同步，默认true
  	config_values[nim::kNIMLoginRetryMaxTimes] = ;		//int 登录重试最大次数，如需设置建议设置大于3次，默认填0，SDK默认设置次数
  	config_root[kNIMGlobalConfig] = config_values;
  
  	//组装SDK独立部署的服务器配置（选填）
  	Json::Value server_values;
  	server_values[kNIMLbsAddress] = "http://xxx"; 			//lbs地址
  	server_values[kNIMNosLbsAddress] = "http://xxx";		//nos lbs地址
  	server_values[kNIMDefaultLinkAddress].append("xxx.xxx.xxx.xxx:xxxx");				//默认的link地址
  	server_values[kNIMDefaultNosUploadAddress].append("http://xxx.xxx.xxx.xxx:xxxx"); 	//默认的nos上传地址
  	server_values[kNIMDefaultNosDownloadAddress].append("http://xxx.xxx.xxx.xxx:xxxx");	//默认的nos下载地址
  	server_values[kNIMRsaPublicKeyModule] = "";				//密钥
  	server_values[kNIMRsaVersion] = 0;						//密钥版本号  	
  	config_root[kNIMPrivateServerSetting] = server_values;
  	config_root[kNIMAppKey] = "45c6af3c98409b18a84451215d0bdd6e"; //必填appkey（此处填写的是测试示例）
  
  	//初始化SDK
  	func("appdata path", "app installation path", config_root.toStyledString().c_str());
  }
  

代理设置

IM SDK 支持 socks4、socks4a、socks5代理,可以通过全局代理设置（同时设置IM、音视频、白板），其中音视频与白板只支持socks5代理，也可以对音视频与白板模块单独设置代理，音视频、白板模块的的代理与全局代理会相互覆盖，以后设置的为准。

API原型

• C++

  **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
  
  **void SetProxy(NIMProxyType type, const std::string& host, int port, const std::string& user, const std::string& password)**
  
  File:nim\_cpp\_vchat.h
  
  Namespace:NIM 
  
  Class：Rts
  
  **void SetProxy(NIMProxyType type, const std::string& host, int port, const std::string& user, const std::string& password)**
  
  File:nim\_cpp\_vchat.h
  
  Namespace:NIM 
  
  Class：VChat
  

• C#

  **static void SetProxy(NIMProxyType type, string host, int port, string user, string password)**
  
  Namespace:NIM 
  
  Class：GlobalAPI
  
  **static void SetProxy(NIMProxyType type, string host, int port, string user, string password)**
  
  Namespace:NIM 
  
  Class：RtsAPI
  
  **static void NIMVChatSetProxy(NIMProxyType type, string host, int port, string user, string password)**
  
  Namespace:NIM 
  
  Class：VChatAPI
  

• C

  **void nim\_global\_set\_proxy(enum NIMProxyType type, const char \*host, int port, const char \*user, const char \*password)**
  
  File:nim\_global.h
  
  **void nim\_vchat\_set\_proxy(enum NIMProxyType type, const char \*host, int port, const char \*user, const char \*password)**
  
  File:nim\_rts.h
  
  **void nim\_vchat\_set\_proxy(enum NIMProxyType type, const char \*host, int port, const char \*user, const char \*password)**
  
  File:nim\_vchat.h
  

参数说明

• C

参数	类型	说明
type	NIMProxyType	代理类型
host	string	代理地址
port	int	端口
user	string	账号
password	string	密码

返回值说明

无返回值。

示例

只示例白板的设置接口

• C++

  void SetProxy()
  {
  	nim::Rts::SetProxy(kNIMProxySocks5, "127.0.0.1", 8080, "123456789", "mimatest123");
  }
  

• C#

  void SetProxy()
  {
  	NIM.VChatAPI.NIMVChatSetProxy(NIMProxyType.kNIMProxySocks5, "127.0.0.1", 8080, "123456789", "mimatest123");
  	NIM.RtsAPI.SetProxy(NIMProxyType.kNIMProxySocks5, "127.0.0.1", 8080, "123456789", "mimatest123");
  
  }
  

• C

  typedef	void(*nim_rts_set_proxy)(enum NIMProxyType type, const char *host, int port, const char *user, const char *password);            
  void SetProxy()
  {
  	nim_rts_set_proxy func = (nim_rts_set_proxy) GetProcAddress(hInst, "nim_rts_set_proxy");
  	func(kNIMProxySocks5, "127.0.0.1", 8080, "123456789", "mimatest123");
  }	
  

SDK清理

在程序退出前，调用接口nim_client_cleanup 进行NIM SDK 的清理工作，然后调用FreeLibrary 函数释放nim.dll，对于清理工作的注意事项请查看后续的"登出/退出和清理SDK"章节。

• C++

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

  File:nim_cpp_client.h

  Namespace:NIM

  Class：Client

• C#

  static void NIM.ClientAPI.Cleanup()

  Namespace:NIM

  Class：ClientAPI

• C

  NIM_SDK_DLL_API void nim_client_cleanup (const char *json_extension)

  File:nim_client.h