文档反馈
文档反馈

初始化

准备工作:将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 介绍

参数说明

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

初始化特殊参数说明

初始化时开发者可以通过设置SDKConfig(C++)/NIMConfig(C#)/json_extenstion(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目录
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,如果选择使用私有服务器,则必填
键常量名 键常量值 值类型 说明
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协议,具体可查阅参数说明列表。

示例

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

音视频初始化

API介绍

在调用音视频网络通话相关功能前,需要在SDK初始化完成后,主动初始化音视频功能。针对私有化,允许传入服务器配置文件。

API原型

参数说明

参数 类型 说明
server_setting_path string 服务器配置文件路径
参数 类型 说明
server_setting_path string 服务器配置文件路径
参数 类型 说明
json_extension string 扩展字段

返回值说明

返回一个bool类型值。若初始化成功返回true,否则返回false。

示例

代理设置

API介绍

互动直播支持socks5代理,可以通过全局代理设置(同时设置IM、音视频互动直播、白板),或者单独设置(只设置音视频互动直播)。两个接口会相互覆盖,以后设置的为准。

API原型

参数说明

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

返回值说明

无返回值。

示例

只示例音视频互动直播的设置接口

音视频清理

API介绍

在调用音视频网络通话相关功能结束后,需要在SDK清理前,主动清理音视频功能。清理音视频功能前,关闭所有设备功能,结束通话

API原型

参数说明

参数 类型 说明
json_extension string 无效扩展字段

返回值说明

无返回值。

示例

打分反馈

API介绍

打分反馈,打分1-5。

API原型

参数说明

参数 类型 说明
rating int 评分,分值为1-5
description string 问题描述
json_extension(C) string 无效扩展字段
cb(C) function 结果回调,见nim_vchat_def.h,返回的json_extension无效。
user_data(C) void* APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!

返回值说明

无返回值。

示例

设置通话回调函数

API介绍

在使用音视频网络通话前,需要先设置通话回调。通过回调会通知音视频事件和相关操作结果。建议在音视频初始化后调用此接口

API原型

参数说明

参数 类型 说明
cb function 音视频通话回调接口
参数 类型 说明
session struct 回调接口封装结构体
参数 类型 说明
cb function 音视频通话回调接口
user_data void* APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

返回值说明

无返回值。

示例

        //注册音视频会话交互回调
        NIM.VChatAPI.SetSessionStatusCb(_vchatHandlers);
    }
×

反馈成功

非常感谢您的反馈,我们会继续努力做得更好。