Instructions for upgrading sdk to version 6.6.6 and above

Weaknesses in using the current SDK

1. SDK introduces many include directories, making it inconvenient to configure the project

2. The C++ wrapper of nim and nim_chatroom contains many duplicate codes

3. The C++ wrapper project only provides static library in md version

4. The SDK introduced in nim_demo is slightly different from the SDK downloaded from the official website in terms of codes, so code comparison is required when upgrading the SDK

For the purpose of solving the above weaknesses, we have adjusted the directories of SDK version 6.6.6 to make it faster and more convenient for users to use, and we managed to maintain the consistency between the SDK and the one introduced in nIM demo, so as to meet the different requirements of different users for the C++ wrapper, including using either the static library (mt/md) mode or dynamic library mode. We have also made some changes to the introduction of the tripartite libraries.

Changes to SDK directory structure

Introduction to SDK directory structure and master files

nim_sdk ..................................................... SDK directory
    include ................................................. SDK introduction inclusive directory
        depend_lib .......................................... Dependent library directory for SDK C++ wrapper
            include ......................................... Dependent library inclusive directory for SDK C++ wrapper
                json ........................................ Json tool inclusive directory
                nim_json_util.h ............................. Auxiliary method of JSON tool
                nim_sdk_util.h .............................. Method of loading/unloading SDK and getting interface
        nim_c_api.h ......................................... c im api introduction file
        nim_chatroom_c_api.h ................................ c chatroom api introduction file
        nim_cpp_api.h ....................................... c++ im api introduction file
        nim_chatroom_cpp_api.h .............................. c++ chatroom api introduction file
        nim_cpp_tools_api.h ................................. nim tool class api introduction file
    public_define ........................................... Introduce SDK common definition directory  c/c++ to definition of data structure
        defines ............................................. im/chatroom/nim_tools data type definition directory
        util ................................................ Compiler switch and basic type definition directory
        nim_sdk_define_include.h ............................ Introduction file for im public data type definitions
        nim_chatroom_define_include.h ....................... Introduction file for chatroom public data type definitions
        nim_tool_define_include.h ........................... Introduction file for nim_tools public data type definitions
        nim_util_include.h .................................. Introduction file for basic type definitions
    src ..................................................... Code directory for realization of c api/C++ wrapper
        c_sdk ............................................... Code directory for c api definitions                
        cpp_sdk ............................................. Code directory for C++ wrapper
            depend_lib ...................................... Code directory for realization of dependent library for c++ encapsulation library
                cpp_wrapper_util_md.sln ..................... Solution text for library project at md/mdd runtime of dependent library for C++ wrapper
                cpp_wrapper_util_mt.sln ..................... Solution text for library project at mt/mtd runtime of dependent library for C++ wrapper
            nim ............................................. Code directory for realization of im C++ wrapper
                nim_sdk_cpp_wrapper_dll.vcxproj ............. Project file of dynamic library for im C++ wrapper 
                nim_sdk_cpp_wrapper_lib_md.vcxproj .......... Library project file at md/mdd runtime of static library for im C++ wrapper
                nim_sdk_cpp_wrapper_lib_mt.vcxproj .......... Library project file at mt/mtd runtime of static library for im C++ wrapper
            nim_chatroom .................................... Code directory for realization of chatrooom C++ wrapper
                nim_chatroom_sdk_cpp_wrapper_dll.vcxproj .... Project file of dynamic library for chatrooom C++ wrapper
                nim_chatroom_sdk_cpp_wrapper_lib_md.vcxproj . - Library project file at md/mdd runtime of static library for chatrooom C++ wrapper
                nim_chatroom_sdk_cpp_wrapper_lib_mt.vcxproj . - Library project file at mt/mtd runtime of static library for chatrooom C++ wrapper
            nim_tools ....................................... Code directory for realization of nim tools C++ wrapper
                audio ....................................... Code directory for realization of C++ wrapper in audio module
                http ........................................ Code directory for realization of C++ wrapper in http module
    libs .................................................... Output directory for C++ wrapper (static library) and dependent library
        win ................................................. Library directory for windows platform
            x86 ............................................. Output directory for x86 platform
            x64 ............................................. Output directory for x64 platform
        iOS ................................................. Library directory for iOS platform
        Mac ................................................. Library directory for Mac platform

Upgrade considerations

SDK introduction

File include directory

Just include nim_sdk folder to import the SDK. custom_app_sdk project of IM demo is taken as an example shown below

Solution for introducing C++ wrapper

The project file of C++ wrapper stored in nim_sdk/src/nim/, nim_sdk/src/nim_chat room/ can be added directly to the solution. IM demo is taken as an example shown below.

Solution for introducing static library

The default output directory of C++ wrapper (static library mode) is nim_sdk/libs/x86/md(mt)/, nim_sdk/libs/x64/md(mt)/, a specified additional library directory can be put under corresponding directory of libs in the library manager according to the selected runtime library and the corresponding static library may be specified for the additional dependencies. custom_app_sdk project of IM demo is taken as an example shown below

How to use C++ dynamic library

The default output directory of C++ wrapper (static library mode) is nim_sdk/bin/x86_dlls/，nim_sdk/bin/x64_dlls/,when C++ wrapper is used in dynamic library mode, the generated nim_sdk_cpp_wrapper_dll.dll/nim_sdk_cpp_wrapper_dll_d.dll, nim_chat room_sdk_cpp_wrapper_dll.dll/nim_chat room_sdk_cpp_wrapper_dll_d.dll can be copied to the specified directory (such as exe output directory). custom_app_sdk project of IM demo is taken as an example shown below

Compilation of C++ wrapper dependency library

vs2013 runtime library pre-generated by C++ wrapper dependency library (depend_lib) is the static library of md(mdd)/mt(mtd), debug/release.
If static libraries of different vs versions (different platform toolsets) are needed for opening nim_sdk/src/cpp_sdk/depend_lib/cpp_wrapper_util_md.sln(cpp_wrapper_util_mt.sln), the developer may update the platform toolset of cpp_wrapper project to generate the corresponding versions of static libraries.

Asynchronous implementation of SDK callback application layer

When the SDK calls back to the application layer, no asynchronous processing in the application layer may block the internal threads of SDK, resulting in issues such as SDK unresponsiveness and disconnection. In order to avoid those issues, conversion should be made to asynchronous processing when the application layer receives the SDK callback information. SDK implements an interface for creating asynchronous callbacks

/** @fn void SetCallbackFunction(const ChatRoom::SDKClosure& callback)
* When your are using the SDK as a dynamic library, set the SDK callback method. In order not to block the SDK thread, the task should be thrown to the application layer thread in the callback
* @param[in] callback	  callback method
* @return void
*/
static void SetCallbackFunction(const SDKClosure& callback);

Take the usage shown below which is in IM demo as an example

nim::Client::SetCallbackFunction([](const StdClosure & task) {
	nbase::ThreadManager::PostTask(ThreadId::kThreadUI, task);
});

About nim_cpp_wrapper_util::Json

nim_cpp_wrapper_util::Json encapsulates jsoncpp into cpp_wrapper_util. For the conversion of nim_cpp_wrapper_util::Json between json (jsoncpp), you can refer to the following codes (nim_demo\tool_kits\shared\cpp_wrapper_util.h in the IM demo)

Json::Value NimCppWrapperJsonValueToJsonValue(const nim_cpp_wrapper_util::Json::Value& param)
{
    Json::Value ret;
    Json::Reader().parse(nim_cpp_wrapper_util::Json::FastWriter().write(param), ret);
    return ret;
}
nim_cpp_wrapper_util::Json::Value JsonValueToNimCppWrapperJsonValue(const Json::Value& param)
{
    nim_cpp_wrapper_util::Json::Value ret;
    nim_cpp_wrapper_util::Json::Reader().parse(Json::FastWriter().write(param), ret);
    return ret;
}