集成方式

SDK内容

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

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

接口调用与约定

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

显式链接

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

隐式链接

#include "nim_client.h"

nim_client_init(app_data_dir, app_install_dir, config_json);

SDK 接口类型

接口限制

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

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

数据格式

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

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

示例

#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
    #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