Implementation of C/C# SDK

Introduction of SDK C# Version

JAKA C version SDK is encapsulated and implemented based on C++ version SDK.

The following is an introduction to the implementation of encapsulating C++ into C interface.

Data Structure Definition in C

The JAKAZuRobot class is defined in the C++ version of the SDK, encapsulating all the data and methods of the robot, but the C language itself does not support the concepts of classes and objects.

Therefore, the C++ object needs to be encapsulated into a structure that can be operated by the C language. The implementation method is as follows.

typedef struct _jkrobot {
  JAKAZuRobot *robot = nullptr; 
  std::string ip = "";          
} jkrobot;

// Struct jkrobot contains a pointer to the C++ class JAKAZuRobot (robot) and the IP address of the robot instance (ip). In this way, we have packaged the C++ object (JAKAZuRobot) into a structure that can be processed by the C language.

Multi-robot Instance Management

In order to manage multiple robot instances, a global std::map<int, jkrobot *> HD container can be used. Its key is an integer and its value is a pointer to the jkrobot structure. This container is used to store and find the robot handle. In the case of multi-robot management, the handle can be used to uniquely identify each robot.

static std::map<int, jkrobot *> HD;
static std::mutex G_HD_MTX;//std::mutex is used to ensure thread-safe access to the HD container. Each time you add, delete, or find an element in the HD container, you need to lock and unlock it.

In order to ensure that there is no data competition when operating the HD container in a multi-threaded environment, the code uses std::mutex for locking operations. G_HD_MTX.lock() and G_HD_MTX.unlock() ensure that each modification of the HD container is performed in a thread-safe environment.

Creating and Destroying Robot Handles

The create_handler function encapsulates the creation and initialization of C++ objects.

A jkrobot object is created in the function and JAKAZuRobot::login_in is called.

If successful, a handle is allocated and the global handle table is updated, and success is returned.

If failed, the robot instance is cleaned up and an error code is returned.

Correspondingly, the destory_handler function is used to destroy the robot instance.

This function finds the robot object through the handle, calls the login_out method, and finally deletes the object to release the memory.

C++ Class Method Encapsulation as C Interface Description

C++ methods are usually object-oriented, but in C language, classes and objects cannot be directly manipulated, so we call C++ class methods indirectly through structures.

To achieve this, the code wraps the C++ method into a C language interface through macro definitions. Using macro definitions simplifies repetitive code.

For example, the JAKA_C_API_DEF_0 macro definition wraps a C++ method like power_on() without passing parameters into a C language function:

#define JAKA_C_API_DEF_0(funcname)                                             \
  errno_t funcname(const JKHD *handle) {                                       \
    HANDLER_CHECK();                                                           \
    return HD[*handle]->robot->funcname();                                     \
  }
//Here, JKHD is a type alias representing the robot handle. The HANDLER_CHECK() macro is used to check whether the robot handle is valid (i.e. whether the corresponding jkrobot structure pointer is nullptr). If the handle is valid, the corresponding C++ method is called through HD[*handle]->robot->funcname().

JAKA_C_API_DEF_0(power_on) //Call C++'s get_robot_status method. 
JAKA_C_API_DEF_0(enable_robot)//Call C++'s set_debug_mode method.

Similar to the encapsulation of other functions with multiple parameters, funcname as a C language function can directly call the C++ member function and pass the corresponding parameters.

#define JAKA_C_API_DEF_1(funcname, type0)                                      \
  errno_t funcname(const JKHD *handle, type0 _v0) {                            \
    HANDLER_CHECK();                                                           \
    return HD[*handle]->robot->funcname(_v0);                                  \
  }

JAKA_C_API_DEF_1(get_robot_status, RobotStatus *)//Call C++'s get_robot_status method. 
JAKA_C_API_DEF_1(set_debug_mode, BOOL)//Call C++'s set_debug_mode method.

Similar to the encapsulation of other functions with multiple parameters, funcname as a C language function can directly call the C++ member function and pass the corresponding parameters.

C# SDK Implementation Instructions

JAKA C# SDK is implemented by encapsulating C SDK.

Encapsulating C functions as C# interfaces is a common cross-language calling method, which is usually implemented through the platform call (P/Invoke) mechanism using the Dlllmport attribute in .NET.

• P/Invoke Introduction: P/Invoke (Platform Invocation Services) allows managed code (such as C#) to interact with native code (such as C or C++). Through P/Invoke, C# code can directly call functions in DLLs written in C or C++ without having to manually write complex interoperability code.

• DllImport attribute: The DllImport attribute is used to declare functions imported from an external dynamic link library (DLL). It allows C# code to call a function written in C or C++ and pass data to the function.

The following is a detailed introduction to the implementation method of encapsulating the C# library based on the C version SDK.

Using DllImport to Encapsulate C Interfaces

The following example code declares a C function called create_handler that accepts an IP address (as a character array char[] or string string) and a handle (an integer reference that returns the identifier of the created handler), and returns an integer indicating the result of the call (which may be a success or failure indicator).

[DllImport("jakaAPI.dll", EntryPoint = "create_handler", ExactSpelling = false, CallingConvention = CallingConvention.Cdecl)]
public static extern int create_handler(char[] ip, ref int handle, bool use_grpc = false);

Tips:

DllImport parameter explanation:

• "jakaAPI.dll": specifies the DLL file name to be called.

• EntryPoint = "create_handler": Specifies the specific function name to be called in the DLL.

• ExactSpelling = false: Tells P/Invoke not to strictly match case.

• CallingConvention = CallingConvention.Cdecl: Specifies the calling convention as the C language standard cdecl, which ensures that the way parameters and return values are cleaned up on the stack is consistent with the C language convention.

There are two points to note:

• Make sure you are familiar with the function declaration in the C dynamic library, including: function name, parameter and return value types, calling convention (such as __cdecl or __stdcall);

• You need to reference the System.Runtime.InteropServices namespace, which provides core support for cross-platform calls.

Packaging Process Considerations

Data Type Mapping

The data types of C and C# are different, so the data types need to be processed accordingly when calling across languages.

Common type mapping table:

C Type	C# Type	illustrate
int	int	Integer direct mapping.
double	double	Floating point type direct mapping.
char*	string or char[]	For C#, you need to specify properties to handle memory.
int*	ref int or out int	Use the ref or out modifier instead of a C pointer.
struct	struct（need StructLayout）	Custom structures require the layout method to be specified using StructLayout.

Relatively complex structures in the C version need to be re-declared in C#, and ensure that the memory layout of the fields is consistent with C.

For example, in C there is the following structure:

/**
 * @brief Cartesian space position data type
 */
typedef struct {
    double x; ///< x axis，unit: mm
    double y; ///< y axis，unit: mm
    double z; ///< z axis，unit: mm
} CartesianTran;

In C#, you need to redefine it using StructLayout:

		/**
        * @brief Cartesian space position data type
        */
		[StructLayout(LayoutKind.Sequential)]
		public struct CartesianTran
		{

			public double x;       ///< x axis，unit: mm
			public double y;       ///< y axis，unit: mm
			public double z;       ///< z axis，unit: mm
		};

• [StructLayout(LayoutKind.Sequential)]：Specifies that fields are stored in the order they are declared, matching the default memory alignment of C.

Encapsulating Optional Parameters and Default Values

C# supports default value parameters, while C usually achieves the same function by explicitly passing parameters. When encapsulating, you can define default values directly in the C# method:

[DllImport("jakaAPI.dll", EntryPoint = "create_handler", CallingConvention = CallingConvention.Cdecl)]
public static extern int create_handler([MarshalAs(UnmanagedType.LPStr)] string ip, ref int handle, bool use_grpc = false);
//In this way, the caller does not need to pass the use_grpc parameter every time it calls, the default value will take effect automatically.

Releases Unmanaged Resources

When a function involves memory allocation (such as string pointers, structure pointers), you need to be careful about releasing resources:

• Use the FreeHGlobal method of the Marshal class to release the allocated memory.

• The corresponding release function needs to be called for the returned unmanaged resources (such as pointers).