N-API整理

一, 函数管理

提供了一组方法，来实现C++方法被调用 和 去调用js方法的功能

1.调用JavaScript方法

/**
* @param env 环境上下文
* @param jsthis 传递给被调用函数的this类型，普通调用，默认使用的全局window对象
* @param func 要调用的方法对象
* @param argc 传递给被调用方法的参数数量
* @param argv 传递的参数列表，是一个napi_value 的数组形式  
* @param result 被唤起的方法,的返回结果
* @return 返回napi_status 来判断该方法是否执行成功
**/
napi_status napi_call_function(napi_env env,
                               napi_value recv,
                               napi_value func,
                               int argc,
                               const napi_value* argv,
                               napi_value* result)

example

//全局对象下存在该方法
// function AddTwo(num) {
//    return  num + 2;
// }

//在全局对象下获取AddTwo方法
napi_value global, add_two, arg;

//获取全局对象
napi_status status = napi_get_global;
assert(status == napi_ok);

//使用全局对象获取函数方法
status = napi_get_named_property(env, global, "AddTwo", &add_two);
assert(status == napi_ok);

//创建参数
status = napi_create_int32(env, 1200, &arg);
assert(status == napi_ok);

napi_value* argv = &arg;
size_t argc = 1;

//创建return_value 存储返回的数据类型
napi_value return_val;

//调用方法
status = napi_call_function(env, global, add_two, argc, argv, &return_val);
assert(status == napi_ok);

//获取执行结果
int32_t = result;
status = napi_get_value_int32(env, return_val, &result);
assert(status == napi_ok);

2.创建JavaScript方法

该函数创建一个共给JavaScript调用的方法， 创建之后，该方法必须通过挂载一个对象暴露出去

/**
* @param env 环境上下文
* @param uft8name 创建的方法名
* @param length 方法名的长度，可以使用NAPI_AUTO_LENGTH 来自动处理
* @param cb 绑定的C++方法
* @param data  用户提供的数据上下文
* @param result 执行结果
* @return 返回napi_status 来判断该方法是否执行成功
**/
napi_status napi_create_function(napi_env env,
                                 const char* utf8name,
                                 size_t length,
                                 napi_callback cb,
                                 void* data,
                                 napi_value* result);

example

//const myaddon = require('./addon');
//myaddon.sayHello();

napi_value SayHello(napi_env env, napi_callback_info info) {
  printf("Hello\n");
  return NULL;
}

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_value fn;
  
  //创建一个方法
  status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
  if (status != napi_ok) return NULL;
  
  //挂载到exports上，对外暴露
  status = napi_set_named_property(env, exports, "sayHello", fn);
  if (status != napi_ok) return NULL;

  return exports;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

napi_get_cb_info

获取JavaScript传递的参数

/**
* @param env 环境上下文
* @param cbinfo 函数信息
* @param argc 参数长度
* @param argv 参数内容，以napi_value 数组形式
* @param thisArg 接收JavaScript 中的this 参数
* @param data 接收一个回调的数据指针
* @return 返回执行结果
**/
napi_status napi_get_cb_info(napi_env env,
                             napi_callback_info cbinfo,
                             size_t* argc,
                             napi_value* argv,
                             napi_value* thisArg,
                             void** data)

napi_get_new_target

当使用new 关键字创建对象时，返回一个 实例的对象， 其他情况返回一个NULL

/**
* @param env 环境上下文
* @parma cbinfo 函数信息
* @param result 创建结果
* @return 返回执行结果
**/
napi_status napi_get_new_target(napi_env env,
                                napi_callback_info cbinfo,
                                napi_value* result)

napi_new_instance

通过一个给定的napi_value值, 创建一个新的JavaScript实例。

//function MyObject(param) {
//  this.param = param;
//}

//const arg = 'hello';
//const value = new MyObject(arg);

// Get the constructor function MyObject
napi_value global, constructor, arg, value;

//获取全局对象
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;

//获取JavaScript对象的引用
status = napi_get_named_property(env, global, "MyObject", &constructor);
if (status != napi_ok) return;

// const arg = "hello" 创建字符参数
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg);
if (status != napi_ok) return;

napi_value* argv = &arg;
size_t argc = 1;

// const value = new MyObject(arg) 使用一个引用，创建一个实例
status = napi_new_instance(env, constructor, argc, argv, &value);

二, 生命周期

1. 生命周期短于原生方法

napi_open_handle_scope

创建一个新的作用域

/**
* @param env 环境上下文
* @param scope 作用域变量 
* @return 返回执行结果
**/
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
                                               napi_handle_scope* result);

napi_close_handle_scope

关闭一个作用域

/**
* @param env 环境上下文
* @param scope 作用域变量
* @return 返回执行结果
**/
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
                                               napi_handle_scope* result);

napi_open_escapable_handle_scope

创建可逃逸的作用域

/**
* @param env 环境上下文
* @param scope 作用域
* @return 返回执行结果
**/
NAPI_EXTERN napi_status
    napi_open_escapable_handle_scope(napi_env env,
                                     napi_handle_scope* result);

napi_close_escapable_handle_scope

关闭可逃逸的作用域

/**
* @param env 环境上下文
* @param scope 作用域
* @return 返回执行结果
**/
NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope);

napi_escape_handle

逃脱作用方法

/**
* @param env 环境上下文
* @param scope 作用域
* @param escape 要逃脱的对象
* @param result 输出逃脱对象的指针
* @return 返回执行结果
**/
napi_status napi_escape_handle(napi_env env,
                               napi_escapable_handle_scope scope,
                               napi_value escapee,
                               napi_value* result);

2. 生命周期长与原生方法

napi_create_reference

创建引用

/**
* @param env 环境上下文
* @param value 需要创建引用的对象
* @param initial_refcount 初始化计数器
* @param result 绑定的引用变量
* @return 返回执行结果
**/
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              int initial_refcount,
                                              napi_ref* result);

napi_delete_reference

删除引用

/**
* @param env 环境变量
* @param  ref 引用
* @return 返回执行结果
**/
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);

napi_reference_ref

递增计数值（+1），并获取

/**
* @param env 环境上下文
* @param ref 引用变量
* @param result 计数值
* @return 返回执行结果
**/
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
                                           napi_ref ref,
                                           int* result);

napi_reference_unref

减少计数值（-1）, 并获取

/**
* @param env 环境上下文
* @param 引用变量
* @param result 计数值
* @return 返回执行结果
**/
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
                                             napi_ref ref,
                                             int* result);

napi_get_reference_value

只是获取计数值

/**
* @param env 环境上下文
* @param ref 引用变量
* @param result 计数值
* @return 返回执行结果
**/
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
                                                 napi_ref ref,
                                                 napi_value* result);

3. 退出与清理实例

napi_add_env_cleanup_hook

在引用退出时，使用指定的参数arg调用函数func, 不同的arg 和相同的func 可以被注册多次，但是相同的arg 和 func 不能被注册多次

/**
* @param env 环境上下文
* @param fun 注册的函数指针
* @param arg 参数指针
* @return 返回执行结果
**/
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env,
                                                     void (*fun)(void* arg),
                                                     void* arg);