Wrapping a Native Object in a Sendable ArkTS Object

When to Use

You can call napi_wrap_sendable to bind an ArkTS Sendable object to a native C++ object. Then, call napi_unwrap_sendable to obtain the C++ object bound to the ArkTS object and perform operations on the C++ object.

Example

1. Declare the APIs, configure compile settings, and register the module.

   Declare the APIs.

   // index.d.ets
   @Sendable
   export class MyObject {
   constructor(arg: number);
   plusOne(): number;
   
   public get value();
   public set value(newVal: number);
   }
   

   Configure compile settings.

   # the minimum version of CMake.
   cmake_minimum_required(VERSION 3.5.0)
   project(napi_wrap_sendable_demo)
   
   set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
   
   if(DEFINED PACKAGE_FIND_FILE)
       include(${PACKAGE_FIND_FILE})
   endif()
   
   include_directories(${NATIVERENDER_ROOT_PATH}
                       ${NATIVERENDER_ROOT_PATH}/include)
   
   add_definitions("-DLOG_DOMAIN=0x0000")
   add_definitions("-DLOG_TAG=\"testTag\"")
   
   add_library(entry SHARED napi_init.cpp)
   target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)
   

   Register the module.

   // napi_init.cpp
   #include "napi/native_api.h"
   #include "hilog/log.h"
   
   // A native class. Its instance is wrapped in a Sendable ArkTS object.
   class MyObject {
   public:
       static napi_value Init(napi_env env, napi_value exports);
       static void Destructor(napi_env env, void *nativeObject, void *finalize_hint);
   
   private:
       explicit MyObject(double value_ = 0);
       ~MyObject();
   
       static napi_value New(napi_env env, napi_callback_info info);
       static napi_value GetValue(napi_env env, napi_callback_info info);
       static napi_value SetValue(napi_env env, napi_callback_info info);
       static napi_value PlusOne(napi_env env, napi_callback_info info);
   
       double value_;
       napi_env env_;
   };
   
   static thread_local napi_ref g_ref = nullptr;
   
   MyObject::MyObject(double value) : value_(value), env_(nullptr) {}
   
   MyObject::~MyObject() {}
   
   void MyObject::Destructor(napi_env env, void *nativeObject, [[maybe_unused]] void *finalize_hint) {
       OH_LOG_INFO(LOG_APP, "MyObject::Destructor called");
       reinterpret_cast<MyObject *>(nativeObject)->~MyObject();
   }
   
   napi_value MyObject::Init(napi_env env, napi_value exports) {
       napi_value num;
       napi_create_double(env, 0, &num);
       napi_property_descriptor properties[] = {
           {"value", nullptr, nullptr, GetValue, SetValue, nullptr, napi_default, nullptr},
           {"plusOne", nullptr, PlusOne, nullptr, nullptr, nullptr, napi_default, nullptr},
       };
   
       napi_value cons;
       // Define a Sendable class MyObject.
       napi_define_sendable_class(env, "MyObject", NAPI_AUTO_LENGTH, New, nullptr,
                               sizeof(properties) / sizeof(properties[0]), properties, nullptr, &cons);
   
       napi_create_reference(env, cons, 1, &g_ref);
       // Mount the MyObject class to the exports object.
       napi_set_named_property(env, exports, "MyObject", cons);
       return exports;
   }
   
   EXTERN_C_START
   // Initialize the module.
   static napi_value Init(napi_env env, napi_value exports) {
       MyObject::Init(env, exports);
       return exports;
   }
   EXTERN_C_END
   
   // Information about the module. Record information such as the Init() function and module name.
   static napi_module nativeModule = {
       .nm_version = 1,
       .nm_flags = 0,
       .nm_filename = nullptr,
       .nm_register_func = Init,
       .nm_modname = "entry",
       .nm_priv = nullptr,
       .reserved = {0},
   };
   
   // When the .so file is loaded, this function is automatically called to register the nativeModule module with the system.
   extern "C" __attribute__((constructor)) void RegisterObjectWrapModule() { napi_module_register(&nativeModule); }
   

2. Wrap a C++ object in a Sendable ArkTS object in a constructor.

   napi_value MyObject::New(napi_env env, napi_callback_info info) {
       OH_LOG_INFO(LOG_APP, "MyObject::New called");
   
       napi_value newTarget;
       napi_get_new_target(env, info, &newTarget);
       if (newTarget != nullptr) {
           // Invoked as the constructor `new MyObject(...)`.
           size_t argc = 1;
           napi_value args[1];
           napi_value jsThis;
           napi_get_cb_info(env, info, &argc, args, &jsThis, nullptr);
   
           double value = 0.0;
           napi_valuetype valuetype;
           napi_typeof(env, args[0], &valuetype);
           if (valuetype != napi_undefined) {
               napi_get_value_double(env, args[0], &value);
           }
   
           MyObject *obj = new MyObject(value);
   
           obj->env_ = env;
           // Use napi_wrap_sendable to wrap obj (the C++ object) in jsThis (the Sendable ArkTS object).
           napi_wrap_sendable(env, jsThis, reinterpret_cast<void *>(obj), MyObject::Destructor, nullptr);
   
           return jsThis;
       } else {
           // Invoked as the plain function `MyObject(...)`.
           size_t argc = 1;
           napi_value args[1];
           napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
   
           napi_value cons;
           napi_get_reference_value(env, g_ref, &cons);
           napi_value instance;
           napi_new_instance(env, cons, argc, args, &instance);
   
           return instance;
       }
   }
   

3. Retrieve the C++ object from the Sendable ArkTS object and perform subsequent operations on the C++ object.

   napi_value MyObject::GetValue(napi_env env, napi_callback_info info) {
       OH_LOG_INFO(LOG_APP, "MyObject::GetValue called");
   
       napi_value jsThis;
       napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr);
   
       MyObject *obj;
       // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations.
       napi_unwrap_sendable(env, jsThis, reinterpret_cast<void **>(&obj));
       napi_value num;
       napi_create_double(env, obj->value_, &num);
   
       return num;
   }
   
   napi_value MyObject::SetValue(napi_env env, napi_callback_info info) {
       OH_LOG_INFO(LOG_APP, "MyObject::SetValue called");
   
       size_t argc = 1;
       napi_value value;
       napi_value jsThis;
   
       napi_get_cb_info(env, info, &argc, &value, &jsThis, nullptr);
   
       MyObject *obj;
       // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations.
       napi_unwrap_sendable(env, jsThis, reinterpret_cast<void **>(&obj));
       napi_get_value_double(env, value, &obj->value_);
   
       return nullptr;
   }
   
   napi_value MyObject::PlusOne(napi_env env, napi_callback_info info) {
       OH_LOG_INFO(LOG_APP, "MyObject::PlusOne called");
   
       napi_value jsThis;
       napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr);
   
       MyObject *obj;
       // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations.
       napi_unwrap_sendable(env, jsThis, reinterpret_cast<void **>(&obj));
       obj->value_ += 1;
       napi_value num;
       napi_create_double(env, obj->value_, &num);
   
       return num;
   }
   

4. ArkTS code:

   import { hilog } from '@kit.PerformanceAnalysisKit';
   import { MyObject } from 'libentry.so';
   
   let object : MyObject = new MyObject(0);
   object.value = 1023;
   hilog.info(0x0000, 'testTag', 'MyObject value after set: %{public}d', object.value);
   hilog.info(0x0000, 'testTag', 'MyObject plusOne: %{public}d', object.plusOne());