集成方式

SDK内容

• 目录结构

text    nim
    |
    |-- include
        |
        |-- api
        |-- export_headers
        |-- util
    |-- libs
        |
        |-- x86
        |-- x86-x64

• 目录说明

  • include：SDK 头文件

    • api: 存放所有SDK功能的接口声明头文件
    • export_headers：存放SDK接口回调函数和JSON key定义头文件
    • util：存放SDK配置和类型定义头文件

  • libs：SDK 提供的动态库，32位和64位动态库分别位于目录x86、x86-x64中

    • libnim.so: SDK IM功能模块
    • libnim_audio.so: 语音录制和播放
    • libnrtc.so: 音视频数据传输模块
    • libnrtc_device.so：音视频采集与播放功能模块

SDK不提供debug版本的动态链接库供开发者调试，如果遇到问题请联系技术支持或在线客服。

接口调用与约定

SDK 提供的所有API 都是 C接口 ，根据模块划分为不同的API 文件。开发者在链接网易云信动态库时可以使用隐式链接和显式链接两种方式，显式链接时，开发者可以在程序进行到任何时间点按需加载动态库，功能完成后如果不需要继续使用NIM可以卸载，更加灵活和节省内存，该模式下开发者只需要将SDK包里 include 目录下的模块定义头文件（命名方式如nim_xxx_def.h）加入到工程项目中；隐式链接下，需要将SDK包里ninclude 目录里的API 头文件（命名方式如nim_xxx.h）以及相关常量定义的头文件等其他头文件一并加入到工程项目中，程序编译时链接云信动态库。一般来说，每个模块都有对应的API 头文件和相关常量的定义头文件，命名上一一对应。下面以nim_client_init接口说明两种调用方式(后面文档中接口示例假定采用隐式链接)。

显式链接

ctypedef bool(*nim_client_init)(const char *app_data_dir, const char *app_install_dir, const char *json_extension);

nim_client_init init_func_ptr;
void* handle = dlopen("libnim.so", RTLD_LAZY);
if(handle)
{
    init_func_ptr = (nim_client_init)dlsym(handle, "nim_client_init");
    init_func_ptr(app_data_dir, app_install_dir, config_json);
}

隐式链接

c#include "nim_client.h"

nim_client_init(app_data_dir, app_install_dir, config_json);

SDK 接口类型

• 全局广播类通知的注册接口

  常见的几类消息或通知是通过这些接口注册的回调函数中通知开发者的，比如收到的消息，会话数据更新，用户相关数据的变更等，开发者需要在登录前提前注册好这些接口，例如：

  c    // 数据同步结果通知(nim_data_sync)
      void nim_data_sync_reg_complete_cb(nim_data_sync_cb_func cb, const void *user_data);
      // 接收会话消息通知(nim_talk)
      void nim_talk_reg_receive_cb(const char *json_extension, nim_talk_receive_cb_func cb, const void *user_data);
      // 接收系统消息通知(nim_sysmsg)
      void nim_sysmsg_reg_sysmsg_cb(const char *json_extension, nim_sysmsg_receive_cb_func cb, const void *user_data);
      // 发送消息结果通知(nim_talk)
      void nim_talk_reg_arc_cb(const char *json_extension, nim_talk_arc_cb_func cb, const void *user_data);
      // 发送自定义系统通知的结果通知(nim_talk)
      void nim_talk_reg_custom_sysmsg_arc_cb(const char *json_extension, nim_custom_sysmsg_arc_cb_func cb, const void *user_data);
      // 群组事件通知(nim_team)
      void nim_team_reg_team_event_cb(const char *json_extension, nim_team_event_cb_func cb, const void *user_data);
      // 帐号被踢通知(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);
      // 将本帐号的其他端踢下线的结果通知(nim_client)
      void nim_client_reg_kickout_other_client_cb(const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);
      // 好友通知
      void nim_friend_reg_changed_cb(const char *json_extension, nim_friend_change_cb_func cb, const void *user_data);
      // 用户特殊关系通知
      void nim_user_reg_special_relationship_changed_cb(const char *json_extension, nim_user_special_relationship_change_cb_func cb, const void *user_data);
  

• 异步接口。

  回调函数作为参数，传入执行接口，然后执行接口时，会触发传入的回调函数。注意，回调函数中如果涉及到跨线程资源的需要开发者切换线程操作，即使不涉及到资源问题，也要保证回调函数中不会处理耗时任务，以免堵塞SDK底层线程。

• 同步接口。

  为方便开发者使用，我们提供了一些同步接口，调用接口获取的内容同步返回，以block命名的都是同步接口。

接口限制

服务器和客户端上线了频控策略，与服务器有交互的接口(接口命名结尾为_online的查询接口以及命令类接口，如同意群邀请等)增加频控控制，开发者关注错误码416。

如果开发者在调用C接口过程中或者解析接口返回结果过程中出现疑问，可以参考和借鉴C++封装层。

数据格式

SDK 使用JSON进行数据传输，接口的输入参数和返回结果都是JSON字符串，用户可以直接组装字符串或者通过序列化/反序列化在JSON和c 结构之间进行转换，推荐使用第二种方式，可阅读性和扩展性更好。接口数据的JSON schema 在头文件中都有说明。在SDK的结果回调中通常都包含错误码来指示操作是否成功，操作成功错误码被设置为 200 (kNIMResSuccess),其它值表明接口调用有错误发生，详细错误码定义请参考nim_res_code_def.h文件中NIMResCode的定义。

该文档中的代码片段使用 json_build 和 jsoncpp进行JSON字符串序列化/反序列化，演示了一些接口输入参数和返回结果的JSON格式和处理方法，用户可以使用其他第三方json库

示例

• 隐式链接

c#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "api/nim_client.h"
#include "api/nim_tools.h"

void nim_login_cb_func(const char *json_params, const void *user_data)
{
    printf("login callback:%s \n",json_params);
}

void nim_logout_cb_func(const char *json_params, const void *user_data)
{
    printf("logout completed,begin to run cleanup ......\n");
    nim_client_cleanup(NULL);
}

int main()
{
    //初始化SDK
    if(nim_client_init("nim_test",NULL,NULL))
    {
        //登录
        nim_client_login("YOUR-APP-KEY","ACCOUNT","PASSWROD",NULL,nim_login_cb_func,NULL);
        getchar();
        //注销
        nim_client_logout(kNIMLogoutAppExit,NULL,nim_logout_cb_func,NULL);
        printf("wait for logout ...... \n");
        getchar();
    }
    else
    {
        printf("nim init failed \n");
    }
    return 0;
}

编译：

    隐式链接动态库时需要设置环境变量LD_LIBRARY_PATH，在运行时系统才能正确加载动态库。

    export LD_LIBRARY_PATH=./libs/x86-x64:$LD_LIBRARY_PATH

    gcc main.c -I./include -I./include/export_headers -L./libs/x86-x64 -lnim

• 显式链接

c    #include <stdio.h>
    #include <dlfcn.h>
    #include "nim_client_def.h"

    //初始化和卸载
    typedef bool (*nim_client_init)(const char *app_data_dir, const char *app_install_dir, const char *json_extension);
    typedef void (*nim_client_cleanup)(const char *json_extension);

    //登录和退出
    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);
    typedef void (*nim_client_logout)(enum NIMLogoutType logout_type, const char *json_extension, nim_json_transport_cb_func cb, const void *user_data);

    //获取函数入口地址
    #define GET_FUNC(function_ptr) \
        (function_ptr)(dlsym(handle, #function_ptr) != NULL ? dlsym(handle, #function_ptr) : NULL)

    nim_client_init init_func_ptr;
    nim_client_cleanup cleanup_func_ptr;
    nim_client_login login_func_ptr;
    nim_client_logout logout_func_ptr;

    int load_nim_lib()
    {
        //从LD_LIBDARY_PATH路径中读取，或者使用完整路径
        void *handle = dlopen("libnim.so", RTLD_LAZY);
        if (!handle)
            return 0;
        init_func_ptr = GET_FUNC(nim_client_init);
        cleanup_func_ptr = GET_FUNC(nim_client_cleanup);
        login_func_ptr = GET_FUNC(nim_client_login);
        logout_func_ptr = GET_FUNC(nim_client_logout);
        return 1;
    }

    void nim_login_cb_func(const char *json_params, const void *user_data)
    {
        printf("login callback:%s \n", json_params);
    }

    void nim_logout_cb_func(const char *json_params, const void *user_data)
    {
        printf("logout completed,begin to run cleanup ......\n");
        cleanup_func_ptr(NULL);
    }

    int main()
    {
        if (load_nim_lib())
        {
            init_func_ptr("nim_test", NULL, NULL);
            login_func_ptr("YOUR-APP-KEY","ACCOUNT","PASSWROD",NULL,nim_login_cb_func,NULL);
            getchar();
            logout_func_ptr(kNIMLogoutAppExit, NULL, nim_logout_cb_func, NULL);
            printf("wait for logout ...... \n");
            getchar();
        }
        return 0;
    }

编译：
export LD_LIBRARY_PATH=./libs/x86-x64:$LD_LIBRARY_PATH
gcc main.c -I./include/export_headers -ldl