From 2bdcaf2d66abfaefad92932d3dbf5af73149eb0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=80=84=E9=94=A6=E7=A8=8B?= <925126483@qq.com> Date: Mon, 16 Jun 2025 23:32:05 +0800 Subject: [PATCH 1/2] =?UTF-8?q?JSVM=E6=96=87=E6=A1=A3=E6=95=B4=E6=94=B9?= =?UTF-8?q?=E4=BC=98=E5=8C=96=EF=BC=9A=201.=20=E8=A1=A5=E5=85=A8=E7=BC=BA?= =?UTF-8?q?=E5=A4=B1=E5=86=85=E5=AE=B9=202.=20=E9=80=9A=E7=AF=87=E6=A3=80?= =?UTF-8?q?=E6=9F=A5=E6=96=87=E6=9C=AC=E6=8F=8F=E8=BF=B0=E4=B8=AD=E7=9A=84?= =?UTF-8?q?=E9=94=99=E5=88=AB=E5=AD=97=203.=20=E7=AE=80=E5=8C=96=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=96=87=E5=AD=97=E6=8F=8F=E8=BF=B0=E4=B8=AD=E7=9A=84?= =?UTF-8?q?=E5=A4=8D=E6=9D=82=E8=AF=AD=E4=B9=89=E3=80=81=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=E6=AD=A7=E4=B9=89=E5=8F=8A=E4=B8=8D=E9=80=9A=E9=A1=BA=E6=8F=8F?= =?UTF-8?q?=E8=BF=B0=E8=AF=AD=E5=8F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h | 212 +++++++++++------- .../native_sdk/ark_runtime/jsvm/jsvm_types.h | 25 ++- 2 files changed, 153 insertions(+), 84 deletions(-) diff --git a/zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h b/zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h index 881c4acc..6c4f6ef2 100644 --- a/zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h +++ b/zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h @@ -53,26 +53,57 @@ #include // NOLINT(modernize-deprecated-headers) #include // NOLINT(modernize-deprecated-headers) -// 使用INT_MAX，只能由预处理器消费。 +/** + * @brief JSVM实验版本号，使用INT_MAX，只能由预处理器消费。 + * + * @since 11 + */ #define JSVM_VERSION_EXPERIMENTAL 2147483647 + +/** + * @brief JSVM版本号。 + * + * 当处于实验阶段JSVM_EXPERIMENTAL时 值为JSVM_VERSION_EXPERIMENTAL（INT_MAX），否则 默认值为8。 + * + * @since 11 + */ #ifndef JSVM_VERSION +/** + * @brief JSVM实验阶段标识。 + * + * @since 11 + */ #ifdef JSVM_EXPERIMENTAL #define JSVM_VERSION JSVM_VERSION_EXPERIMENTAL #else - #define JSVM_VERSION 8 #endif #endif #include "jsvm_types.h" -#ifndef JSVM_EXTERN -#ifdef _WIN32 /** * @brief 对外可见。 * + * WIN环境下为： __declspec(dllexport) + * 在Windows上，当构建动态链接库（DLL）时，用于告知编译器一个函数或变量从DLL中导出，使其可以被其他程序使用。 + * wasm环境下为： __attribute__((visibility("default"))) \ + * __attribute__((__import_module__("jsvm"))) + * ①__attribute__ 是 GCC 和 Clang 编译器用来添加特殊属性的语法。 + * ②__attribute__((visibility("default"))): 这个属性控制符号（函数/变量名）的可见性。 + * "default" 意味着这个符号是公开的、可导出的。在 Wasm 模块中，这使得函数可以被宿主环境（通常是 JavaScript）调用。 + * ③__attribute__((__import_module__("jsvm"))): 这是最关键的部分。 + * 它告诉编译器，被这个宏修饰的函数不是在本 C/C++ 代码中实现的，而是需要从外部导入。 + * 其他环境下为： __attribute__((visibility("default"))) + * 此类清空通常对应于 Linux、macOS 和其他类 Unix 系统。 + * 与 Windows 的 dllexport 类似，这个属性用于从共享库（在 Linux 上是 .so 文件，在 macOS 上是 .dylib 文件）中导出符号。 + * 当使用 -fvisibility=hidden 编译标志（这是一个常见的优化和安全实践，默认隐藏所有符号）时， + * 只有明确标记为 visibility("default") 的符号才是公开可见的。 + * * @since 11 */ +#ifndef JSVM_EXTERN +#ifdef _WIN32 #define JSVM_EXTERN __declspec(dllexport) #elif defined(__wasm__) #define JSVM_EXTERN \ @@ -90,8 +121,27 @@ */ #define JSVM_AUTO_LENGTH SIZE_MAX +/** + * @brief 一个预处理指令，用来检查是否正在使用C++编译器进行编译的、只有C++编译器才会预定义的宏。 + */ #ifdef __cplusplus -#define EXTERN_C_START extern "C" { +/** + * @brief 用于告知编译器按C Code编译以下代码段的段起始标识： + * + * 当预处理指令__cplusplus检查到C++编译器正在进行编译时：EXTERN_C_START被赋值为"extern "C" {" ，表示其后代码为C代码。 + * 当预处理指令__cplusplus检查到不是C++编译器时，无须标记。 + * + * @since 11 + */ +#define EXTERN_C_START extern "C" { +/** + * @brief 用于告知编译器按C Code编译以下代码段的段终止标识： + * + * 当使用预处理指令__cplusplus检查到C++编译器正在编译时：EXTERN_C_START被赋值为"}" ，表示C代码到此为止。 + * 当预处理指令__cplusplus检查到不是C++编译器时，无须标记。 + * + * @since 11 + */ #define EXTERN_C_END } #else #define EXTERN_C_START @@ -146,7 +196,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetMicrotaskPolicy(JSVM_VM vm, JSVM_EXTERN JSVM_Status OH_JSVM_DestroyVM(JSVM_VM vm); /** - * @brief 创建 JavaScript Proxy。 该接口等价于在 JavaScript 中执行 new Proxy(target, handler)。 + * @brief 创建JavaScript Proxy，等价于在 JavaScript 中执行 new Proxy(target, handler)。 * * @param env 调用 JSVM-API 的环境。 * @param target 表示用于创建代理的 JavaScript 对象 @@ -166,7 +216,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateProxy(JSVM_Env env, JSVM_Value* result); /** - * @brief 判断传入的值是否为 JavaScript Proxy。 + * @brief 判断传入值value是否为 JavaScript Proxy。 * * @param env 调用 JSVM-API 的环境。 * @param value 需要检查的值。 @@ -288,7 +338,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CloseEnvScope(JSVM_Env env, JSVM_EnvScope scope); /** - * @brief 将检索给定环境的虚拟机实例。 + * @brief 检索给定环境的虚拟机实例。 * * @param env 目标环境，JSVM-API接口将在该环境下调用。 * @param result 给定环境的虚拟机实例。 @@ -426,7 +476,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetInstanceData(JSVM_Env env, void* finalizeHint); /** - * @brief 检索通过OH_JSVM_SetInstanceData()与当前运行的JSVM环境相关联的数据。 + * @brief 检索通过调用OH_JSVM_SetInstanceData()与当前运行JSVM环境产生关联的数据。 * 如果未设置任何关联数据，该函数调用将成功，且data设置为NULL。 * * @param env 调用JSVM-API的环境。 @@ -439,7 +489,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetInstanceData(JSVM_Env env, void** data); /** - * @brief 检索JSVM_ExtendedErrorInfo结构，其中包含有关发生的最后一个错误的信息。 + * @brief 检索JSVM_ExtendedErrorInfo结构，其中包含发生的最后一个错误的有关信息。 * 返回的JSVM_ExtendedErrorInfo的内容仅在对同一env调用JSVM-API函数之前有效。 * 这包括对OH_JSVM_IsExceptionPending的调用，因此可能经常需要复制信息以便以后使用。 * error_message中返回的指针指向一个静态定义的字符串，因此如果你在调用另一个JSVM-API @@ -467,7 +517,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_Throw(JSVM_Env env, JSVM_Value error); /** - * @brief 会抛出带有所提供文本的JavaScript Error。 + * @brief 抛出带有所提供文本的JavaScript Error。 * * @param env 调用JSVM-API的环境。 * @param code 要在错误上设置的可选错误代码。 @@ -481,7 +531,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ThrowError(JSVM_Env env, const char* msg); /** - * @brief 会抛出带有所提供文本的JavaScript TypeError。 + * @brief 抛出带有所提供文本的JavaScript TypeError。 * * @param env 调用JSVM-API的环境。 * @param code 要在错误上设置的可选错误代码。 @@ -495,7 +545,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ThrowTypeError(JSVM_Env env, const char* msg); /** - * @brief 会抛出带有所提供文本的JavaScript RangeError。 + * @brief 抛出带有所提供文本的JavaScript RangeError。 * * @param env 调用JSVM-API的环境。 * @param code 要在错误上设置的可选错误代码。 @@ -509,7 +559,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ThrowRangeError(JSVM_Env env, const char* msg); /** - * @brief 会抛出带有所提供文本的JavaScript SyntaxError。 + * @brief 抛出带有所提供文本的JavaScript SyntaxError。 * * @param env 调用JSVM-API的环境。 * @param code 要在错误上设置的可选错误代码。 @@ -641,7 +691,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_OpenHandleScope(JSVM_Env env, JSVM_HandleScope* result); /** - * @brief 关闭传入的作用域。必须按照创建作用域的相反顺序关闭作用域。 + * @brief （必须）按照创建作用域的相反顺序关闭传入的作用域。 * * @param env 调用JSVM-API的环境。 * @param scope 表示要关闭的作用域。 @@ -653,7 +703,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CloseHandleScope(JSVM_Env env, JSVM_HandleScope scope); /** - * @brief 会打开一个新作用域，从中可以将一个对象提升到外部作用域。 + * @brief 打开一个可以将某对象从其中提到外部作用域的新作用域。 * * @param env 调用JSVM-API的环境。 * @param result 代表新作用域。 @@ -665,7 +715,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_OpenEscapableHandleScope(JSVM_Env env, JSVM_EscapableHandleScope* result); /** - * @brief 关闭传入的作用域。必须按照创建作用域的相反顺序关闭作用域。 + * @brief （必须）按照创建作用域的相反顺序关闭传入的作用域。 * 即使存在挂起的JavaScript异常，也可以调用此JSVM_API。 * * @param env 调用JSVM-API的环境。 @@ -819,7 +869,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateArraybuffer(JSVM_Env env, JSVM_Value* result); /** - * @brief 申请一段给 array buffer 使用的 BackingStore 内存。 + * @brief 申请一段 BackingStore 内存给 array buffer 使用。 * * @param byteLength BackingStore 内存的大小。 * @param initialized BackingStore 内存初始化的方式。 @@ -920,7 +970,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateObject(JSVM_Env env, JSVM_Value* result); /** - * @brief 从UTF8 编码的C字符串创建JavaScript symbol值。 + * @brief 用UTF8编码的C字符串创建JavaScript symbol值。 * * @param env 调用JSVM-API的环境。 * @param description 可选的JSVM_Value，它指的是要设置为符号描述的JavaScript string。 @@ -952,10 +1002,9 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SymbolFor(JSVM_Env env, JSVM_Value* result); /** - * @brief 基于已有的ArrayBuffer对象，创建一个JavaScript TypedArray对象。TypedArray - * 对象在底层数据缓冲区上提供了一个类似数组的视图，其中每个元素都具有 - * 相同的底层二进制标量数据类型。要求：（length* 元素大小）+ byteOffset - * 小于等于传入的数组的大小（以字节为单位）。否则，将抛出范围错误（RangeError）。 + * @brief 基于已有的ArrayBuffer对象，创建一个JavaScript TypedArray对象。 + * TypedArray对象在底层数据缓冲区上提供了一个类似数组的视图，其中每个元素都具有相同的底层二进制标量数据类型。 + * 要求：（length* 元素大小）+ byteOffset不大于传入数组的大小（byte数）。否则，抛出范围错误（RangeError）。 * * @param env 调用JSVM-API的环境。 * @param type TypedArray中元素的标量数据类型。 @@ -976,10 +1025,9 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypedarray(JSVM_Env env, JSVM_Value* result); /** - * @brief 基于已有的ArrayBuffer对象，创建一个JavaScript DataView对象。DataView - * 对象在底层数据缓冲区上提供了一个类似数组的视图，其中的元素可以具有不同的大小和类型。 - * 要求：二进制的length + byteOffset - * 小于或等于传入的数组的大小（以字节为单位）。否则，将抛出范围错误（RangeError）。 + * @brief 基于已有的ArrayBuffer对象，创建一个JavaScript DataView对象。 + * DataView对象在底层数据缓冲区上提供了一个类似数组的视图，其中的元素可以具有不同的大小和类型。 + * 要求：二进制的length + byteOffset不大于传入数组的大小（byte数）。否则，抛出范围错误（RangeError）。 * * @param env 调用JSVM-API的环境。 * @param length DataView中的元素个数。 @@ -997,7 +1045,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateDataview(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C int32_t类型的值转换为JavaScript number类型。 + * @brief 将一个C int32_t类型值转换为JavaScript number类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表示的整数值。 @@ -1011,7 +1059,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt32(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C uint32_t类型的值转换为JavaScript number类型。 + * @brief 将一个C uint32_t类型值转换为JavaScript number类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表示的无符号整数值。 @@ -1025,7 +1073,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateUint32(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C int64_t类型的值转换为JavaScript number类型。 + * @brief 将一个C int64_t类型值转换为JavaScript number类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表示的整数值。 @@ -1039,7 +1087,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt64(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C double类型的值转换为JavaScript number类型。 + * @brief 将一个C double类型值转换为JavaScript number类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表现的双精度值。 @@ -1053,7 +1101,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateDouble(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C int64_t类型的值转换为JavaScript BigInt类型。 + * @brief 将一个C int64_t类型值转换为JavaScript BigInt类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表现的整数值。 @@ -1067,7 +1115,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintInt64(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C uint64_t类型的值转换为JavaScript BigInt类型。 + * @brief 将一个C uint64_t类型值转换为JavaScript BigInt类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表示的无符号整数值。 @@ -1081,7 +1129,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintUint64(JSVM_Env env, JSVM_Value* result); /** - * @brief 将一组无符号64位字转换为单个BigInt值。 + * @brief 将一组64位无符号比特位转换为单个BigInt值。 * * @param env 调用JSVM-API的环境。 * @param signBit 确定生成的BigInt是正数还是负数。 @@ -1101,7 +1149,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintWords(JSVM_Env env, JSVM_Value* result); /** - * @brief 将采用ISO-8859-1编码的C字符串转换为JavaScript string值。 + * @brief 将ISO-8859-1编码的C字符串转换为JavaScript字符串值。 * 复制原生字符串。 * * @param env 调用JSVM-API的环境。 @@ -1118,7 +1166,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringLatin1(JSVM_Env env, JSVM_Value* result); /** - * @brief 将采用UTF16-LE编码的C字符串转换为JavaScript字符串值。 + * @brief 将UTF16-LE编码的C字符串转换为JavaScript字符串值。 * 复制原生字符串。 * * @param env 调用JSVM-API的环境。 @@ -1135,7 +1183,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf16(JSVM_Env env, JSVM_Value* result); /** - * @brief 从UTF8编码的C字符串创建JavaScript string值。 + * @brief 用UTF8编码的C字符串创建JavaScript字符串值。 * 复制原生字符串。 * * @param env 调用JSVM-API的环境。 @@ -1249,7 +1297,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetDataviewInfo(JSVM_Env env, size_t* byteOffset); /** - * @brief 返回给定JavaScript Date的时间值的C双精度基础类型。如果调用成功，返回JSVM_OK。 + * @brief 返回与给定的JavaScript Date时间值等价的C双精度基础类型值。如果调用成功，返回JSVM_OK。 * 如果传入一个非JavaScript Date类型的JSVM_Value，返回JSVM_DATA_EXPECTED。 * * @param env 调用JSVM-API的环境。 @@ -1265,7 +1313,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetDateValue(JSVM_Env env, double* result); /** - * @brief 返回给定JavaScript Boolean的C布尔基础类型等价值。 + * @brief 返回与给定的JavaScript Boolean等价的C布尔基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript Boolean。 @@ -1280,7 +1328,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBool(JSVM_Env env, bool* result); /** - * @brief 返回给定JavaScript number的C双精度基础类型等价值。 + * @brief 返回与给定的JavaScript number等价的C双精度基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1295,7 +1343,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueDouble(JSVM_Env env, double* result); /** - * @brief 返回给定JavaScript BigInt的C int64_t基础类型等价值。 + * @brief 返回与给定的JavaScript BigInt等价的C int64_t基础类型值。 * 如果需要，它将截断该值，将lossless设置为false。 * * @param env 调用JSVM-API的环境。 @@ -1313,7 +1361,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintInt64(JSVM_Env env, bool* lossless); /** - * @brief 返回给定JavaScript BigInt的C uint64_t基础类型等价值。 + * @brief 返回与给定的JavaScript BigInt等价的C uint64_t基础类型值。 * 如果需要，它将截断该值，将lossless设置为false。 * * @param env 调用JSVM-API的环境。 @@ -1366,7 +1414,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueExternal(JSVM_Env env, void** result); /** - * @brief 返回给定JavaScript number的C int32基础类型等价值。 + * @brief 返回与给定的JavaScript number等价的C int32基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1381,7 +1429,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt32(JSVM_Env env, int32_t* result); /** - * @brief 返回给定JavaScript number的C int64基础类型等价值。 + * @brief 返回与给定的JavaScript number等价的C int64基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1396,7 +1444,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt64(JSVM_Env env, int64_t* result); /** - * @brief 返回对应于传入值的ISO-8859-1编码字符串 + * @brief 返回与传入值对应的ISO-8859-1编码字符串 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1416,7 +1464,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringLatin1(JSVM_Env env, size_t* result); /** - * @brief 返回对应于传入值的UTF8编码字符串。 + * @brief 返回与传入值对应的UTF8编码字符串。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript字符串。 @@ -1436,7 +1484,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf8(JSVM_Env env, size_t* result); /** - * @brief 基于传入的值，查询对应的采用UTF16编码的字符串。 + * @brief 查询与传入值对应的UTF16编码字符串。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript字符串。 @@ -1456,7 +1504,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf16(JSVM_Env env, size_t* result); /** - * @brief 返回给定JavaScript number的C uint_32基础类型等价值。 + * @brief 返回与给定的JavaScript number等价的C uint_32基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1471,7 +1519,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueUint32(JSVM_Env env, uint32_t* result); /** - * @brief 返回用于表示给定布尔值的JavaScript单例对象。 + * @brief 返回表示给定布尔值的JavaScript单例对象。 * * @param env 调用JSVM-API的环境。 * @param value 要检索的布尔值。 @@ -1760,7 +1808,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetPropertyNames(JSVM_Env env, JSVM_Value* result); /** - * @brief 返回一个数组，其中包含此对象的可用属性的名称。 + * @brief 返回包含object所有可用属性名称的数组。 * * @param env 调用JSVM-API的环境。 * @param object 从中检索属性的对象。 @@ -1783,7 +1831,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetAllPropertyNames(JSVM_Env env, JSVM_Value* result); /** - * @brief 为传入的object设置一个属性。 + * @brief 为传入的object设置名为key的属性。 * * @param env 调用JSVM-API的环境。 * @param object 将进行属性设置的对象。 @@ -1800,7 +1848,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetProperty(JSVM_Env env, JSVM_Value value); /** - * @brief 从传入的object中获取请求的属性。 + * @brief 从传入的object中获取名为key的属性。 * * @param env 调用JSVM-API的环境。 * @param object 从中检索属性的对象。 @@ -1817,7 +1865,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetProperty(JSVM_Env env, JSVM_Value* result); /** - * @brief 检查传入的Object是否具有指定命名的属性。 + * @brief 检查传入的Object是否具有命名为key的属性。 * * @param env 调用JSVM-API的环境。 * @param object 待查询的对象。 @@ -1834,7 +1882,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_HasProperty(JSVM_Env env, bool* result); /** - * @brief 尝试从object中删除key自己的属性。 + * @brief 尝试从object中删除名为key的属性。 * * @param env 调用JSVM-API的环境。 * @param object 待查询的对象。 @@ -1851,13 +1899,13 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DeleteProperty(JSVM_Env env, bool* result); /** - * @brief 检查传入的Object是否具有命名的自己的属性。key必须是string或symbol， - * 否则将抛出错误。JSVM-API不会执行任何数据类型之间的转换。 + * @brief 检查传入的Object是否具有名为key的属性。 + * key必须是string或symbol，否则将抛出错误。JSVM-API不会执行任何数据类型之间的转换。 * * @param env 调用JSVM-API的环境。 * @param object 待查询的对象。 - * @param key 要检查其存在的自有属性的名称。 - * @param result 表示对象上是否存在该自身属性。 + * @param key 要检查的是否存在的属性名称。 + * @param result 表示对象是否存在该属性。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n @@ -1869,8 +1917,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_HasOwnProperty(JSVM_Env env, bool* result); /** - * @brief 此方法等效于调用OH_JSVM_SetProperty， - * 其中，通过utf8Name传入的字符串用于创建JSVM_Value。 + * @brief 此方法等效于object调用OH_JSVM_SetProperty设置名为`utf8Name`的属性。 * * @param env 调用JSVM-API的环境。 * @param object 要对其设置属性的对象。 @@ -1887,8 +1934,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetNamedProperty(JSVM_Env env, JSVM_Value value); /** - * @brief 此方法等效于调用OH_JSVM_GetProperty， - * 其中，通过utf8Name传入的字符串用于创建JSVM_Value。 + * @brief 此方法等效于object调用OH_JSVM_GetProperty获取名为`utf8Name`的属性对象。 * * @param env 调用JSVM-API的环境。 * @param object 从中检索属性的对象。 @@ -1905,8 +1951,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetNamedProperty(JSVM_Env env, JSVM_Value* result); /** - * @brief 此方法等效于使用从作为utf8Name传入的字符串创建的JSVM_Value - * 调用OH_JSVM_HasProperty。 + * @brief 此方法等效于object对象调用OH_JSVM_HasProperty查询其内部是否存在名为`utf8Name`的属性。 * * @param env 调用JSVM-API的环境。 * @param object 待查询的对象。 @@ -1991,9 +2036,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DeleteElement(JSVM_Env env, bool* result); /** - * @brief 通过此方法可以在给定对象上高效定义多个属性， - * 这些属性使用属性描述符进行定义。通过一个属性描述符的数组， - * 此API将为对象依次设置数组中的属性。 + * @brief 通过此方法可以在给定对象上高效定义多个属性，这些属性使用属性描述符进行定义。 + * 通过一个属性描述符的数组，此API将为对象依次设置数组中的属性。 * * @param env 调用JSVM-API的环境。 * @param object 待进行属性检索的对象。 @@ -2011,8 +2055,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DefineProperties(JSVM_Env env, const JSVM_PropertyDescriptor* properties); /** - * @brief 冻结指定的对象。这样可以防止为其添加新的属性、删除现有属性、更改现有属性的 - * 可枚举性、可配置性或可写性、或者更改现有属性的值。它还可以防止改变对象的原型。 + * @brief 冻结指定的对象，防止为其添加新的属性、删除现有属性、更改现有属性的 + * 可枚举性/可配置性/可写性、更改现有属性的值、改变对象原型等操作。 * * @param env 调用JSVM-API的环境。 * @param object 待冻结的对象。 @@ -2025,7 +2069,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ObjectFreeze(JSVM_Env env, JSVM_Value object); /** - * @brief 封装指定的对象。这样可以防止为其添加新的属性并且将所有现有属性标记为不可配置。 + * @brief 封装指定的对象，防止为其添加新的属性并将所有现有属性标记为不可配置。 * * @param env 调用JSVM-API的环境。 * @param object 待封装的对象。 @@ -2165,8 +2209,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DefineClass(JSVM_Env env, JSVM_Value* result); /** - * @brief 在JavaScript对象中封装native实例。native实例 - * 后续可以通过OH_JSVM_Unwrap()进行检索。 + * @brief 在JavaScript对象中封装native实例，该实例后续可以通过OH_JSVM_Unwrap()进行检索。 * * @param env 调用JSVM-API的环境。 * @param jsObject 将成为原生对象封装器的JavaScript对象。 @@ -2204,7 +2247,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_Unwrap(JSVM_Env env, void** result); /** - * @brief 使用OH_JSVM_Wrap()检索先前封装在JavaScript对象js_object中的native实例并移除封装。 + * @brief 使用OH_JSVM_Wrap()检索先前封装在JavaScript对象——js_object中的native实例并移除封装。 * 如果finalize回调与封装相关联，则当JavaScript对象被垃圾回收时将不再调用它。 * * @param env 调用JSVM-API的环境。 @@ -2392,7 +2435,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_IsPromise(JSVM_Env env, bool* isPromise); /** - * @brief 注册处理 Promise 兑现/拒绝的回调函数。 + * @brief 注册 处理Promise兑现/拒绝的 回调函数。 * @param env 调用 JSVM-API 的环境。 * @param promise 需要注册回调的 promise。 * @param onFulfilled 该函数在 promise 兑现后调用。 @@ -2547,7 +2590,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CloseInspector(JSVM_Env env); * 发送Runtime.runIfWaitingForDebugger命令。 * * @param env 调用JSVM-API的环境。 - * @param breakNextLine 是否在下一行JavaScript代码中中断。传递“是”，后续将暂停在运行下一行JS代码时，继续运行需要开发者通过调试器的调试按钮控制JS的执行。 + * @param breakNextLine 是否在下一行JavaScript代码中中断。breakNextLine为true将暂停运行下一行JS代码，开发者需要通过调试器的调试按钮控制JS继续执行。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n @@ -2557,7 +2600,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_WaitForDebugger(JSVM_Env env, bool breakNextLine); /** - * @brief 定义一个具有给定类名、构造函数、属性和回调处理程序的JavaScript类属性操作包括getter、setter、deleter、enumerator等，并作为函数回调进行调用。 + * @brief 定义一个具有给定类名、构造函数、属性和回调处理程序的JavaScript类， + * 属性操作包括getter、setter、deleter、enumerator等，并作为函数回调进行调用。 * * @param env 调用JSVM-API的环境。 * @param utf8name JavaScript类构造函数的名称。 @@ -2775,7 +2819,7 @@ JSVM_Status JSVM_CDECL OH_JSVM_IsConstructor(JSVM_Env env, bool* isConstructor); /** - * @brief 此API返回与输入对应的正则表达式的JavaScript值。 + * @brief 此API返回与输入的JavaScript字符串对应的正则表达式对象。 * 接口可能会抛出异常。 * * @param env 调用JSVM-API的环境。 @@ -2907,7 +2951,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateFunctionWithScript(JSVM_Env env, JSVM_Value* result); /** - * @brief 启动虚拟机内任务队列的运行。这个任务队列可以通过外部事件循环来执行。 + * @brief 启动虚拟机内任务队列，这个任务队列可以通过外部事件循环执行。 * * @param vm 启动任务队列的虚拟机实例。 * @param result 表示任务队列是否成功启动。 @@ -2941,7 +2985,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_PerformMicrotaskCheckpoint(JSVM_VM vm); JSVM_EXTERN JSVM_Status OH_JSVM_RetainScript(JSVM_Env env, JSVM_Script script); /** - * @brief 此函数释放由OH_JSVM_RetainScript保留的脚本，释放后应避免对传入 script 的再次使用. + * @brief 释放由 OH_JSVM_RetainScript 保留的脚本，释放后应避免对传入 script 的再次使用. * * @param env 调用该API的环境. * @param script 包含要释放的脚本的JavaScript字符串. @@ -2953,7 +2997,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_RetainScript(JSVM_Env env, JSVM_Script script); JSVM_EXTERN JSVM_Status OH_JSVM_ReleaseScript(JSVM_Env env, JSVM_Script script); /** - * @brief 此函数打开一个命名为传入 name 的 inspector，为其打开对应 pid 的 unix domain 端口. + * @brief 打开一个名为 name 的 inspector，为其打开对应 pid 的 unix domain 端口. * * @param env 调用该API的环境. * @param pid 用于标识 inspector 连接的进程ID. @@ -3301,11 +3345,13 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolIterator(JSVM_Env env, JSVM_Value* resu * * @since 18 */ -JSVM_EXTERN JSVM_Status OH_JSVM_TraceStart(size_t count, const JSVM_TraceCategory* categories, - const char* tag, size_t eventsCount); +JSVM_EXTERN JSVM_Status OH_JSVM_TraceStart(size_t count, + const JSVM_TraceCategory* categories, + const char* tag, + size_t eventsCount); /** - * @brief 对所有 JSVM 运行时，结束采集指定 Trace 类别的信息。(线程不安全) + * @brief 对所有 JSVM 运行时，停止采集指定 Trace 类别的信息。(线程不安全) * * @param stream 输出流回调函数，实现接收 Trace 数据功能。 * @param streamData 的输出流指针，用于辅助输出流回调函数进行数据输出。 diff --git a/zh-cn/native_sdk/ark_runtime/jsvm/jsvm_types.h b/zh-cn/native_sdk/ark_runtime/jsvm/jsvm_types.h index 824bb595..71162d39 100644 --- a/zh-cn/native_sdk/ark_runtime/jsvm/jsvm_types.h +++ b/zh-cn/native_sdk/ark_runtime/jsvm/jsvm_types.h @@ -46,9 +46,32 @@ #include // NOLINT(modernize-deprecated-headers) #if !defined __cplusplus || (defined(_MSC_VER) && _MSC_VER < 1900) +/** + * @brief 为uint16_t创建一个别名——char16_t + * + * 这段代码的核心目的是确保 char16_t 这个类型在所有目标编译环境中都可用，即使在一些不支持它的旧环境里。 + * char16_t 是 C++11 标准中引入的一个新的基本数据类型，专门用于存储16位字符，通常用来表示UTF-16编码的字符。 + * + * 如果编译器本身不认识char16_t，手动创建一个底层实现是16位无符号的整数类型。 + * 前置生效条件为：当前编译器——非C++编译器编译 || 是微软Visual C++编译器且版本早于Visual Studio 2015（不含）。 + * + * @since 11 + */ typedef uint16_t char16_t; #endif +/** + * @brief 为不同平台统一函数约定调用（Calling Convention）的宏 + * + * 如果在 Windows 上，JSVM_CDECL 宏会被展开为 __cdecl。 + * __cdecl是 C/C++ 语言在 x86 架构上的默认调用约定。它的主要特点是：参数从右到左压入栈、调用者 (caller) 负责清理栈。 + * 虽然 __cdecl 是默认的，但在 Windows API 编程中，还存在其他CC，如 __stdcall（被调用者清理栈，Win32 API常用）和 __fastcall（部分参数用寄存器传递）。 + * 通过显式指定__cdecl，确保即使项目全局编译设置被修改为其他约定，被这个宏修饰的函数依然可以保持 __cdecl 约定，从而避免不匹配问题。 + * + * 在大多数非 Windows 系统（如遵循 System V ABI 的 Linux/macOS）上，通常只有一种标准的调用约定，无须指定JSVM_CDECL。 + * + * @since 11 + */ #ifndef JSVM_CDECL #ifdef _WIN32 #define JSVM_CDECL __cdecl @@ -618,7 +641,7 @@ typedef struct { typedef JSVM_PropertyHandlerConfigurationStruct* JSVM_PropertyHandlerCfg; /** - * @brief Source code information. + * @brief 某段JavaScript代码的原始信息，如sourceMap路径、源文件名、源文件中的起始行/列号等. * * @since 12 */ -- Gitee From bd66aaaa2ca7a8c660f9a3782b64d6249bf4530c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=80=84=E9=94=A6=E7=A8=8B?= <925126483@qq.com> Date: Mon, 16 Jun 2025 23:32:05 +0800 Subject: [PATCH 2/2] =?UTF-8?q?JSVM=E6=96=87=E6=A1=A3=E6=95=B4=E6=94=B9?= =?UTF-8?q?=E4=BC=98=E5=8C=96=EF=BC=9A=201.=20=E8=A1=A5=E5=85=A8=E7=BC=BA?= =?UTF-8?q?=E5=A4=B1=E5=86=85=E5=AE=B9=202.=20=E9=80=9A=E7=AF=87=E6=A3=80?= =?UTF-8?q?=E6=9F=A5=E6=96=87=E6=9C=AC=E6=8F=8F=E8=BF=B0=E4=B8=AD=E7=9A=84?= =?UTF-8?q?=E9=94=99=E5=88=AB=E5=AD=97=203.=20=E7=AE=80=E5=8C=96=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=96=87=E5=AD=97=E6=8F=8F=E8=BF=B0=E4=B8=AD=E7=9A=84?= =?UTF-8?q?=E5=A4=8D=E6=9D=82=E8=AF=AD=E4=B9=89=E3=80=81=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=E6=AD=A7=E4=B9=89=E5=8F=8A=E4=B8=8D=E9=80=9A=E9=A1=BA=E6=8F=8F?= =?UTF-8?q?=E8=BF=B0=E8=AF=AD=E5=8F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 4. 针对函数的返回值做了通篇校验及二次修改 Signed-off-by: 逄锦程 <925126483@qq.com> --- zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h | 307 ++++++++++++------ .../native_sdk/ark_runtime/jsvm/jsvm_types.h | 25 +- 2 files changed, 231 insertions(+), 101 deletions(-) diff --git a/zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h b/zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h index 881c4acc..a7937cc9 100644 --- a/zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h +++ b/zh-cn/native_sdk/ark_runtime/jsvm/jsvm.h @@ -53,26 +53,57 @@ #include // NOLINT(modernize-deprecated-headers) #include // NOLINT(modernize-deprecated-headers) -// 使用INT_MAX，只能由预处理器消费。 +/** + * @brief JSVM实验版本号，使用INT_MAX，只能由预处理器消费。 + * + * @since 11 + */ #define JSVM_VERSION_EXPERIMENTAL 2147483647 + +/** + * @brief JSVM版本号。 + * + * 当处于实验阶段JSVM_EXPERIMENTAL时 值为JSVM_VERSION_EXPERIMENTAL（INT_MAX），否则 默认值为8。 + * + * @since 11 + */ #ifndef JSVM_VERSION +/** + * @brief JSVM实验阶段标识。 + * + * @since 11 + */ #ifdef JSVM_EXPERIMENTAL #define JSVM_VERSION JSVM_VERSION_EXPERIMENTAL #else - #define JSVM_VERSION 8 #endif #endif #include "jsvm_types.h" -#ifndef JSVM_EXTERN -#ifdef _WIN32 /** * @brief 对外可见。 * + * WIN环境下为： __declspec(dllexport) + * 在Windows上，当构建动态链接库（DLL）时，用于告知编译器一个函数或变量从DLL中导出，使其可以被其他程序使用。 + * wasm环境下为： __attribute__((visibility("default"))) \ + * __attribute__((__import_module__("jsvm"))) + * ①__attribute__ 是 GCC 和 Clang 编译器用来添加特殊属性的语法。 + * ②__attribute__((visibility("default"))): 这个属性控制符号（函数/变量名）的可见性。 + * "default" 意味着这个符号是公开的、可导出的。在 Wasm 模块中，这使得函数可以被宿主环境（通常是 JavaScript）调用。 + * ③__attribute__((__import_module__("jsvm"))): 这是最关键的部分。 + * 它告诉编译器，被这个宏修饰的函数不是在本 C/C++ 代码中实现的，而是需要从外部导入。 + * 其他环境下为： __attribute__((visibility("default"))) + * 此类清空通常对应于 Linux、macOS 和其他类 Unix 系统。 + * 与 Windows 的 dllexport 类似，这个属性用于从共享库（在 Linux 上是 .so 文件，在 macOS 上是 .dylib 文件）中导出符号。 + * 当使用 -fvisibility=hidden 编译标志（这是一个常见的优化和安全实践，默认隐藏所有符号）时， + * 只有明确标记为 visibility("default") 的符号才是公开可见的。 + * * @since 11 */ +#ifndef JSVM_EXTERN +#ifdef _WIN32 #define JSVM_EXTERN __declspec(dllexport) #elif defined(__wasm__) #define JSVM_EXTERN \ @@ -90,8 +121,27 @@ */ #define JSVM_AUTO_LENGTH SIZE_MAX +/** + * @brief 一个预处理指令，用来检查是否正在使用C++编译器进行编译的、只有C++编译器才会预定义的宏。 + */ #ifdef __cplusplus -#define EXTERN_C_START extern "C" { +/** + * @brief 用于告知编译器按C Code编译以下代码段的段起始标识： + * + * 当预处理指令__cplusplus检查到C++编译器正在进行编译时：EXTERN_C_START被赋值为"extern "C" {" ，表示其后代码为C代码。 + * 当预处理指令__cplusplus检查到不是C++编译器时，无须标记。 + * + * @since 11 + */ +#define EXTERN_C_START extern "C" { +/** + * @brief 用于告知编译器按C Code编译以下代码段的段终止标识： + * + * 当使用预处理指令__cplusplus检查到C++编译器正在编译时：EXTERN_C_START被赋值为"}" ，表示C代码到此为止。 + * 当预处理指令__cplusplus检查到不是C++编译器时，无须标记。 + * + * @since 11 + */ #define EXTERN_C_END } #else #define EXTERN_C_START @@ -106,6 +156,8 @@ EXTERN_C_START * @param options 用于初始化JavaScript虚拟机的选项。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_Init(const JSVM_InitOptions* options); @@ -130,6 +182,9 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateVM(const JSVM_CreateVMOptions* options, * @param vm 用于设置微任务执行策略的虚拟机实例。 * @param policy 执行微任务的策略。 * @return 如果接口调用成功，返回 JSVM_OK。 + * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_INVALID_ARG } 表示传入参数不合法。\n + * * @since 18 */ JSVM_EXTERN JSVM_Status OH_JSVM_SetMicrotaskPolicy(JSVM_VM vm, @@ -141,22 +196,22 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetMicrotaskPolicy(JSVM_VM vm, * @param vm 待销毁的虚拟机实例。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_INVALID_ARG } 表示传入参数不合法。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_DestroyVM(JSVM_VM vm); /** - * @brief 创建 JavaScript Proxy。 该接口等价于在 JavaScript 中执行 new Proxy(target, handler)。 + * @brief 创建JavaScript Proxy，等价于在 JavaScript 中执行 new Proxy(target, handler)。 * * @param env 调用 JSVM-API 的环境。 * @param target 表示用于创建代理的 JavaScript 对象 * @param handler 表示定义了拦截什么操作及如何处理被拦截操作的 JavaScript 对象。 * @param result 表示创建的 JavaScript 代理。 * @return 返回执行状态码。 - * {@link JSVM_OK } 表示接口调用成功。 \n - * {@link JSVM_INVALID_ARG } 如果任意参数为空。 \n + * {@link JSVM_OK } 表示接口调用成功。\n * {@link JSVM_OBJECT_EXPECTED} 如果 target 或 handler 非 JS 对象。\n - * {@link JSVM_PENDING_EXCEPTION} 如果存在待处理的 JS 异常。 \n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * * @since 18 */ @@ -166,14 +221,13 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateProxy(JSVM_Env env, JSVM_Value* result); /** - * @brief 判断传入的值是否为 JavaScript Proxy。 + * @brief 判断传入值value是否为 JavaScript Proxy。 * * @param env 调用 JSVM-API 的环境。 * @param value 需要检查的值。 * @param isProxy 表示是否为 JavaScript Proxy。 * @return 返回执行状态码。 - * {@link JSVM_OK } 表示接口调用成功。 \n - * {@link JSVM_INVALID_ARG } 如果任意参数为空。\n + * {@link JSVM_OK } 表示接口调用成功。\n * * @since 18 */ @@ -188,9 +242,8 @@ JSVM_Status JSVM_CDECL OH_JSVM_IsProxy(JSVM_Env env, * @param value 需要获取目标对象的代理。 * @param result 代理的目标对象。 * @return 返回执行状态码。 - * {@link JSVM_OK } 表示接口调用成功。 \n - * {@link JSVM_INVALID_ARG } 如果任意参数为空。 \n - * {@link JSVM_INVALID_TYPE} 如果 value 非 Javascript Proxy。 \n + * {@link JSVM_OK } 表示接口调用成功。\n + * {@link JSVM_INVALID_TYPE} 如果 value 非 Javascript Proxy。\n * * @since 18 */ @@ -288,7 +341,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CloseEnvScope(JSVM_Env env, JSVM_EnvScope scope); /** - * @brief 将检索给定环境的虚拟机实例。 + * @brief 检索给定环境的虚拟机实例。 * * @param env 目标环境，JSVM-API接口将在该环境下调用。 * @param result 给定环境的虚拟机实例。 @@ -313,6 +366,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetVM(JSVM_Env env, * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_STRING_EXPECTED } 表示传入的参数不是string类型。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CompileScript(JSVM_Env env, @@ -338,6 +392,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CompileScript(JSVM_Env env, * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_STRING_EXPECTED } 表示传入的参数不是string类型。\n * {@link JSVM_GENERIC_FAILURE } 表示执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 12 */ JSVM_EXTERN JSVM_Status OH_JSVM_CompileScriptWithOrigin(JSVM_Env env, @@ -359,8 +414,10 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CompileScriptWithOrigin(JSVM_Env env, * @param result 编译后的脚本。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_INVALID_ARG } 表示传入的 data 是空指针。\n * {@link JSVM_STRING_EXPECTED } 表示传入的参数不是string类型。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 12 */ JSVM_EXTERN JSVM_Status OH_JSVM_CompileScriptWithOptions(JSVM_Env env, @@ -401,6 +458,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateCodeCache(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_RunScript(JSVM_Env env, @@ -426,7 +484,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetInstanceData(JSVM_Env env, void* finalizeHint); /** - * @brief 检索通过OH_JSVM_SetInstanceData()与当前运行的JSVM环境相关联的数据。 + * @brief 检索通过调用OH_JSVM_SetInstanceData()与当前运行JSVM环境产生关联的数据。 * 如果未设置任何关联数据，该函数调用将成功，且data设置为NULL。 * * @param env 调用JSVM-API的环境。 @@ -439,7 +497,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetInstanceData(JSVM_Env env, void** data); /** - * @brief 检索JSVM_ExtendedErrorInfo结构，其中包含有关发生的最后一个错误的信息。 + * @brief 检索JSVM_ExtendedErrorInfo结构，其中包含发生的最后一个错误的有关信息。 * 返回的JSVM_ExtendedErrorInfo的内容仅在对同一env调用JSVM-API函数之前有效。 * 这包括对OH_JSVM_IsExceptionPending的调用，因此可能经常需要复制信息以便以后使用。 * error_message中返回的指针指向一个静态定义的字符串，因此如果你在调用另一个JSVM-API @@ -467,7 +525,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_Throw(JSVM_Env env, JSVM_Value error); /** - * @brief 会抛出带有所提供文本的JavaScript Error。 + * @brief 抛出带有所提供文本的JavaScript Error。 * * @param env 调用JSVM-API的环境。 * @param code 要在错误上设置的可选错误代码。 @@ -481,7 +539,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ThrowError(JSVM_Env env, const char* msg); /** - * @brief 会抛出带有所提供文本的JavaScript TypeError。 + * @brief 抛出带有所提供文本的JavaScript TypeError。 * * @param env 调用JSVM-API的环境。 * @param code 要在错误上设置的可选错误代码。 @@ -495,7 +553,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ThrowTypeError(JSVM_Env env, const char* msg); /** - * @brief 会抛出带有所提供文本的JavaScript RangeError。 + * @brief 抛出带有所提供文本的JavaScript RangeError。 * * @param env 调用JSVM-API的环境。 * @param code 要在错误上设置的可选错误代码。 @@ -509,7 +567,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ThrowRangeError(JSVM_Env env, const char* msg); /** - * @brief 会抛出带有所提供文本的JavaScript SyntaxError。 + * @brief 抛出带有所提供文本的JavaScript SyntaxError。 * * @param env 调用JSVM-API的环境。 * @param code 要在错误上设置的可选错误代码。 @@ -641,19 +699,20 @@ JSVM_EXTERN JSVM_Status OH_JSVM_OpenHandleScope(JSVM_Env env, JSVM_HandleScope* result); /** - * @brief 关闭传入的作用域。必须按照创建作用域的相反顺序关闭作用域。 + * @brief （必须）按照创建作用域的相反顺序关闭传入的作用域。 * * @param env 调用JSVM-API的环境。 * @param scope 表示要关闭的作用域。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_HANDLE_SCOPE_MISMATCH } 表示执行失败。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CloseHandleScope(JSVM_Env env, JSVM_HandleScope scope); /** - * @brief 会打开一个新作用域，从中可以将一个对象提升到外部作用域。 + * @brief 打开一个可以将某对象从其中提到外部作用域的新作用域。 * * @param env 调用JSVM-API的环境。 * @param result 代表新作用域。 @@ -665,7 +724,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_OpenEscapableHandleScope(JSVM_Env env, JSVM_EscapableHandleScope* result); /** - * @brief 关闭传入的作用域。必须按照创建作用域的相反顺序关闭作用域。 + * @brief （必须）按照创建作用域的相反顺序关闭传入的作用域。 * 即使存在挂起的JavaScript异常，也可以调用此JSVM_API。 * * @param env 调用JSVM-API的环境。 @@ -811,6 +870,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateArrayWithLength(JSVM_Env env, * @param result 代表JavaScript ArrayBuffer的JSVM_Value。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CreateArraybuffer(JSVM_Env env, @@ -819,7 +879,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateArraybuffer(JSVM_Env env, JSVM_Value* result); /** - * @brief 申请一段给 array buffer 使用的 BackingStore 内存。 + * @brief 申请一段 BackingStore 内存给 array buffer 使用。 * * @param byteLength BackingStore 内存的大小。 * @param initialized BackingStore 内存初始化的方式。 @@ -855,7 +915,7 @@ JSVM_Status JSVM_CDECL OH_JSVM_FreeArrayBufferBackingStoreData(void *data); * @param arrayBufferSize array buffer 的大小，单位是字节。 * @param result 接收 array buffer 地址的指针。 * @return 返回执行状态码 JSVM_Status。 - * {@link JSVM_OK } 表示执行成功。 \n + * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_INVALID_ARG } 表示触发了下面描述的异常情况之一：\n * 1. offset + arrayBufferSize > backingStoreSize \n * 2. backingStoreSize 或者 arrayBufferSize 为 0 \n @@ -879,6 +939,7 @@ JSVM_Status JSVM_CDECL OH_JSVM_CreateArrayBufferFromBackingStoreData(JSVM_Env en * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CreateDate(JSVM_Env env, @@ -920,7 +981,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateObject(JSVM_Env env, JSVM_Value* result); /** - * @brief 从UTF8 编码的C字符串创建JavaScript symbol值。 + * @brief 用UTF8编码的C字符串创建JavaScript symbol值。 * * @param env 调用JSVM-API的环境。 * @param description 可选的JSVM_Value，它指的是要设置为符号描述的JavaScript string。 @@ -952,10 +1013,9 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SymbolFor(JSVM_Env env, JSVM_Value* result); /** - * @brief 基于已有的ArrayBuffer对象，创建一个JavaScript TypedArray对象。TypedArray - * 对象在底层数据缓冲区上提供了一个类似数组的视图，其中每个元素都具有 - * 相同的底层二进制标量数据类型。要求：（length* 元素大小）+ byteOffset - * 小于等于传入的数组的大小（以字节为单位）。否则，将抛出范围错误（RangeError）。 + * @brief 基于已有的ArrayBuffer对象，创建一个JavaScript TypedArray对象。 + * TypedArray对象在底层数据缓冲区上提供了一个类似数组的视图，其中每个元素都具有相同的底层二进制标量数据类型。 + * 要求：（length* 元素大小）+ byteOffset不大于传入数组的大小（byte数）。否则，抛出范围错误（RangeError）。 * * @param env 调用JSVM-API的环境。 * @param type TypedArray中元素的标量数据类型。 @@ -966,6 +1026,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SymbolFor(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_INVALID_ARG } 表示传入的参数不合法。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypedarray(JSVM_Env env, @@ -976,10 +1037,9 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypedarray(JSVM_Env env, JSVM_Value* result); /** - * @brief 基于已有的ArrayBuffer对象，创建一个JavaScript DataView对象。DataView - * 对象在底层数据缓冲区上提供了一个类似数组的视图，其中的元素可以具有不同的大小和类型。 - * 要求：二进制的length + byteOffset - * 小于或等于传入的数组的大小（以字节为单位）。否则，将抛出范围错误（RangeError）。 + * @brief 基于已有的ArrayBuffer对象，创建一个JavaScript DataView对象。 + * DataView对象在底层数据缓冲区上提供了一个类似数组的视图，其中的元素可以具有不同的大小和类型。 + * 要求：二进制的length + byteOffset不大于传入数组的大小（byte数）。否则，抛出范围错误（RangeError）。 * * @param env 调用JSVM-API的环境。 * @param length DataView中的元素个数。 @@ -988,6 +1048,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypedarray(JSVM_Env env, * @param result 表示JavaScript DataView对象的JSVM_Value。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_INVALID_ARG } 表示传入的参数不合法。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CreateDataview(JSVM_Env env, @@ -997,7 +1059,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateDataview(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C int32_t类型的值转换为JavaScript number类型。 + * @brief 将一个C int32_t类型值转换为JavaScript number类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表示的整数值。 @@ -1011,7 +1073,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt32(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C uint32_t类型的值转换为JavaScript number类型。 + * @brief 将一个C uint32_t类型值转换为JavaScript number类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表示的无符号整数值。 @@ -1025,7 +1087,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateUint32(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C int64_t类型的值转换为JavaScript number类型。 + * @brief 将一个C int64_t类型值转换为JavaScript number类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表示的整数值。 @@ -1039,7 +1101,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt64(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C double类型的值转换为JavaScript number类型。 + * @brief 将一个C double类型值转换为JavaScript number类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表现的双精度值。 @@ -1053,7 +1115,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateDouble(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C int64_t类型的值转换为JavaScript BigInt类型。 + * @brief 将一个C int64_t类型值转换为JavaScript BigInt类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表现的整数值。 @@ -1067,7 +1129,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintInt64(JSVM_Env env, JSVM_Value* result); /** - * @brief 将C uint64_t类型的值转换为JavaScript BigInt类型。 + * @brief 将一个C uint64_t类型值转换为JavaScript BigInt类型值。 * * @param env 调用JSVM-API的环境。 * @param value 要在JavaScript中表示的无符号整数值。 @@ -1081,7 +1143,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintUint64(JSVM_Env env, JSVM_Value* result); /** - * @brief 将一组无符号64位字转换为单个BigInt值。 + * @brief 将一组64位无符号比特位转换为单个BigInt值。 * * @param env 调用JSVM-API的环境。 * @param signBit 确定生成的BigInt是正数还是负数。 @@ -1101,7 +1163,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintWords(JSVM_Env env, JSVM_Value* result); /** - * @brief 将采用ISO-8859-1编码的C字符串转换为JavaScript string值。 + * @brief 将ISO-8859-1编码的C字符串转换为JavaScript字符串值。 * 复制原生字符串。 * * @param env 调用JSVM-API的环境。 @@ -1110,6 +1172,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintWords(JSVM_Env env, * @param result 表示JavaScript字符串的JSVM_Value。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringLatin1(JSVM_Env env, @@ -1118,7 +1181,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringLatin1(JSVM_Env env, JSVM_Value* result); /** - * @brief 将采用UTF16-LE编码的C字符串转换为JavaScript字符串值。 + * @brief 将UTF16-LE编码的C字符串转换为JavaScript字符串值。 * 复制原生字符串。 * * @param env 调用JSVM-API的环境。 @@ -1127,6 +1190,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringLatin1(JSVM_Env env, * @param result 代表JavaScript string的JSVM_Value。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf16(JSVM_Env env, @@ -1135,7 +1199,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf16(JSVM_Env env, JSVM_Value* result); /** - * @brief 从UTF8编码的C字符串创建JavaScript string值。 + * @brief 用UTF8编码的C字符串创建JavaScript字符串值。 * 复制原生字符串。 * * @param env 调用JSVM-API的环境。 @@ -1144,6 +1208,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf16(JSVM_Env env, * @param result 代表JavaScript字符串的JSVM_Value。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf8(JSVM_Env env, @@ -1160,6 +1225,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf8(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_ARRAY_EXPECTED } 表示传入的参数不是Array类型。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_GetArrayLength(JSVM_Env env, @@ -1193,6 +1259,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetArraybufferInfo(JSVM_Env env, * @param result 表示给定对象的原型。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_GetPrototype(JSVM_Env env, @@ -1238,7 +1305,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetTypedarrayInfo(JSVM_Env env, * @param byteOffset 开始投影DataView的数据缓冲区中的字节偏移量。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n - * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_INVALID_ARG } 表示传入参数非外部的JSVM_Value。 * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_GetDataviewInfo(JSVM_Env env, @@ -1249,7 +1316,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetDataviewInfo(JSVM_Env env, size_t* byteOffset); /** - * @brief 返回给定JavaScript Date的时间值的C双精度基础类型。如果调用成功，返回JSVM_OK。 + * @brief 返回与给定的JavaScript Date时间值等价的C双精度基础类型值。如果调用成功，返回JSVM_OK。 * 如果传入一个非JavaScript Date类型的JSVM_Value，返回JSVM_DATA_EXPECTED。 * * @param env 调用JSVM-API的环境。 @@ -1258,6 +1325,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetDataviewInfo(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_DATE_EXPECTED } 表示传入参数不是Date类型。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_GetDateValue(JSVM_Env env, @@ -1265,7 +1333,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetDateValue(JSVM_Env env, double* result); /** - * @brief 返回给定JavaScript Boolean的C布尔基础类型等价值。 + * @brief 返回与给定的JavaScript Boolean等价的C布尔基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript Boolean。 @@ -1280,7 +1348,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBool(JSVM_Env env, bool* result); /** - * @brief 返回给定JavaScript number的C双精度基础类型等价值。 + * @brief 返回与给定的JavaScript number等价的C双精度基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1295,7 +1363,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueDouble(JSVM_Env env, double* result); /** - * @brief 返回给定JavaScript BigInt的C int64_t基础类型等价值。 + * @brief 返回与给定的JavaScript BigInt等价的C int64_t基础类型值。 * 如果需要，它将截断该值，将lossless设置为false。 * * @param env 调用JSVM-API的环境。 @@ -1313,7 +1381,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintInt64(JSVM_Env env, bool* lossless); /** - * @brief 返回给定JavaScript BigInt的C uint64_t基础类型等价值。 + * @brief 返回与给定的JavaScript BigInt等价的C uint64_t基础类型值。 * 如果需要，它将截断该值，将lossless设置为false。 * * @param env 调用JSVM-API的环境。 @@ -1366,7 +1434,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueExternal(JSVM_Env env, void** result); /** - * @brief 返回给定JavaScript number的C int32基础类型等价值。 + * @brief 返回与给定的JavaScript number等价的C int32基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1381,7 +1449,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt32(JSVM_Env env, int32_t* result); /** - * @brief 返回给定JavaScript number的C int64基础类型等价值。 + * @brief 返回与给定的JavaScript number等价的C int64基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1396,7 +1464,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt64(JSVM_Env env, int64_t* result); /** - * @brief 返回对应于传入值的ISO-8859-1编码字符串 + * @brief 返回与传入值对应的ISO-8859-1编码字符串 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1416,7 +1484,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringLatin1(JSVM_Env env, size_t* result); /** - * @brief 返回对应于传入值的UTF8编码字符串。 + * @brief 返回与传入值对应的UTF8编码字符串。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript字符串。 @@ -1436,7 +1504,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf8(JSVM_Env env, size_t* result); /** - * @brief 基于传入的值，查询对应的采用UTF16编码的字符串。 + * @brief 查询与传入值对应的UTF16编码字符串。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript字符串。 @@ -1456,7 +1524,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf16(JSVM_Env env, size_t* result); /** - * @brief 返回给定JavaScript number的C uint_32基础类型等价值。 + * @brief 返回与给定的JavaScript number等价的C uint_32基础类型值。 * * @param env 调用JSVM-API的环境。 * @param value 代表JavaScript number。 @@ -1471,7 +1539,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetValueUint32(JSVM_Env env, uint32_t* result); /** - * @brief 返回用于表示给定布尔值的JavaScript单例对象。 + * @brief 返回表示给定布尔值的JavaScript单例对象。 * * @param env 调用JSVM-API的环境。 * @param value 要检索的布尔值。 @@ -1528,6 +1596,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetUndefined(JSVM_Env env, * @param result 代表强制的JavaScript Boolean。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToBool(JSVM_Env env, @@ -1543,6 +1612,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToBool(JSVM_Env env, * @param result 代表强制的JavaScript number。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_NUMBER_EXPECTED} 如果传入的JavaScript值无法转换成Number。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToNumber(JSVM_Env env, @@ -1557,6 +1627,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToNumber(JSVM_Env env, * @param result 代表强制的JavaScript object。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_OBJECT_EXPECTED} 如果传入的JavaScript值无法转换成Object。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToObject(JSVM_Env env, @@ -1572,6 +1643,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToObject(JSVM_Env env, * @param result 代表强制的JavaScript string。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_STRING_EXPECTED} 如果传入的JavaScript值无法转换成String。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToString(JSVM_Env env, @@ -1606,6 +1678,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_Typeof(JSVM_Env env, * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_FUNCTION_EXPECTED } 表示传入的参数不是Function类型。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_Instanceof(JSVM_Env env, @@ -1692,6 +1765,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_IsDataview(JSVM_Env env, * @param result 表示两个JSVM_Value对象是否相等。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_StrictEquals(JSVM_Env env, @@ -1709,6 +1783,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_StrictEquals(JSVM_Env env, * @param result 表示两个JSVM_Value对象是否相等。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 12 */ JSVM_EXTERN JSVM_Status OH_JSVM_Equals(JSVM_Env env, @@ -1753,6 +1828,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_IsDetachedArraybuffer(JSVM_Env env, * 可以使用OH_JSVM_GetArrayLength以及OH_JSVM_GetElement对结果进行迭代。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_INVALID_ARG } 表示传入的参数不合法。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_GetPropertyNames(JSVM_Env env, @@ -1760,7 +1837,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetPropertyNames(JSVM_Env env, JSVM_Value* result); /** - * @brief 返回一个数组，其中包含此对象的可用属性的名称。 + * @brief 返回包含object所有可用属性名称的数组。 * * @param env 调用JSVM-API的环境。 * @param object 从中检索属性的对象。 @@ -1783,7 +1860,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetAllPropertyNames(JSVM_Env env, JSVM_Value* result); /** - * @brief 为传入的object设置一个属性。 + * @brief 为传入的object设置名为key的属性。 * * @param env 调用JSVM-API的环境。 * @param object 将进行属性设置的对象。 @@ -1792,6 +1869,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetAllPropertyNames(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_SetProperty(JSVM_Env env, @@ -1800,7 +1878,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetProperty(JSVM_Env env, JSVM_Value value); /** - * @brief 从传入的object中获取请求的属性。 + * @brief 从传入的object中获取名为key的属性。 * * @param env 调用JSVM-API的环境。 * @param object 从中检索属性的对象。 @@ -1809,6 +1887,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetProperty(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_GetProperty(JSVM_Env env, @@ -1817,7 +1896,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetProperty(JSVM_Env env, JSVM_Value* result); /** - * @brief 检查传入的Object是否具有指定命名的属性。 + * @brief 检查传入的Object是否具有命名为key的属性。 * * @param env 调用JSVM-API的环境。 * @param object 待查询的对象。 @@ -1826,6 +1905,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetProperty(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_HasProperty(JSVM_Env env, @@ -1834,7 +1914,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_HasProperty(JSVM_Env env, bool* result); /** - * @brief 尝试从object中删除key自己的属性。 + * @brief 尝试从object中删除名为key的属性。 * * @param env 调用JSVM-API的环境。 * @param object 待查询的对象。 @@ -1843,6 +1923,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_HasProperty(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_DeleteProperty(JSVM_Env env, @@ -1851,16 +1932,18 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DeleteProperty(JSVM_Env env, bool* result); /** - * @brief 检查传入的Object是否具有命名的自己的属性。key必须是string或symbol， - * 否则将抛出错误。JSVM-API不会执行任何数据类型之间的转换。 + * @brief 检查传入的Object是否具有名为key的属性。 + * key必须是string或symbol，否则将抛出错误。JSVM-API不会执行任何数据类型之间的转换。 * * @param env 调用JSVM-API的环境。 * @param object 待查询的对象。 - * @param key 要检查其存在的自有属性的名称。 - * @param result 表示对象上是否存在该自身属性。 + * @param key 要检查的是否存在的属性名称。 + * @param result 表示对象是否存在该属性。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_NAME_EXPECTED } 表示期望传入名字不合法。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_HasOwnProperty(JSVM_Env env, @@ -1869,8 +1952,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_HasOwnProperty(JSVM_Env env, bool* result); /** - * @brief 此方法等效于调用OH_JSVM_SetProperty， - * 其中，通过utf8Name传入的字符串用于创建JSVM_Value。 + * @brief 此方法等效于object调用OH_JSVM_SetProperty设置名为`utf8Name`的属性。 * * @param env 调用JSVM-API的环境。 * @param object 要对其设置属性的对象。 @@ -1879,6 +1961,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_HasOwnProperty(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_SetNamedProperty(JSVM_Env env, @@ -1887,8 +1970,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetNamedProperty(JSVM_Env env, JSVM_Value value); /** - * @brief 此方法等效于调用OH_JSVM_GetProperty， - * 其中，通过utf8Name传入的字符串用于创建JSVM_Value。 + * @brief 此方法等效于object调用OH_JSVM_GetProperty获取名为`utf8Name`的属性对象。 * * @param env 调用JSVM-API的环境。 * @param object 从中检索属性的对象。 @@ -1897,6 +1979,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetNamedProperty(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_GetNamedProperty(JSVM_Env env, @@ -1905,8 +1988,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetNamedProperty(JSVM_Env env, JSVM_Value* result); /** - * @brief 此方法等效于使用从作为utf8Name传入的字符串创建的JSVM_Value - * 调用OH_JSVM_HasProperty。 + * @brief 此方法等效于object对象调用OH_JSVM_HasProperty查询其内部是否存在名为`utf8Name`的属性。 * * @param env 调用JSVM-API的环境。 * @param object 待查询的对象。 @@ -1915,6 +1997,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetNamedProperty(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_HasNamedProperty(JSVM_Env env, @@ -1932,6 +2015,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_HasNamedProperty(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_SetElement(JSVM_Env env, @@ -1949,6 +2033,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetElement(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_GetElement(JSVM_Env env, @@ -1966,6 +2051,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetElement(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_HasElement(JSVM_Env env, @@ -1983,6 +2069,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_HasElement(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_DeleteElement(JSVM_Env env, @@ -1991,9 +2078,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DeleteElement(JSVM_Env env, bool* result); /** - * @brief 通过此方法可以在给定对象上高效定义多个属性， - * 这些属性使用属性描述符进行定义。通过一个属性描述符的数组， - * 此API将为对象依次设置数组中的属性。 + * @brief 通过此方法可以在给定对象上高效定义多个属性，这些属性使用属性描述符进行定义。 + * 通过一个属性描述符的数组，此API将为对象依次设置数组中的属性。 * * @param env 调用JSVM-API的环境。 * @param object 待进行属性检索的对象。 @@ -2003,6 +2089,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DeleteElement(JSVM_Env env, * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_INVALID_ARG } 表示传入的参数不合法。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_DefineProperties(JSVM_Env env, @@ -2011,8 +2098,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DefineProperties(JSVM_Env env, const JSVM_PropertyDescriptor* properties); /** - * @brief 冻结指定的对象。这样可以防止为其添加新的属性、删除现有属性、更改现有属性的 - * 可枚举性、可配置性或可写性、或者更改现有属性的值。它还可以防止改变对象的原型。 + * @brief 冻结指定的对象，防止为其添加新的属性、删除现有属性、更改现有属性的 + * 可枚举性/可配置性/可写性、更改现有属性的值、改变对象原型等操作。 * * @param env 调用JSVM-API的环境。 * @param object 待冻结的对象。 @@ -2025,7 +2112,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ObjectFreeze(JSVM_Env env, JSVM_Value object); /** - * @brief 封装指定的对象。这样可以防止为其添加新的属性并且将所有现有属性标记为不可配置。 + * @brief 封装指定的对象，防止为其添加新的属性并将所有现有属性标记为不可配置。 * * @param env 调用JSVM-API的环境。 * @param object 待封装的对象。 @@ -2073,6 +2160,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CallFunction(JSVM_Env env, * @param result 表示新创建函数的JavaScript函数对象。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_CreateFunction(JSVM_Env env, @@ -2154,6 +2242,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_NewInstance(JSVM_Env env, * @param result 表示类的构造函数的JSVM_Value。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_DefineClass(JSVM_Env env, @@ -2165,8 +2254,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DefineClass(JSVM_Env env, JSVM_Value* result); /** - * @brief 在JavaScript对象中封装native实例。native实例 - * 后续可以通过OH_JSVM_Unwrap()进行检索。 + * @brief 在JavaScript对象中封装native实例，该实例后续可以通过OH_JSVM_Unwrap()进行检索。 * * @param env 调用JSVM-API的环境。 * @param jsObject 将成为原生对象封装器的JavaScript对象。 @@ -2177,6 +2265,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_DefineClass(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_INVALID_ARG } 表示传入的参数不合法。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_Wrap(JSVM_Env env, @@ -2197,6 +2286,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_Wrap(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_INVALID_ARG } 表示传入的参数不合法。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_Unwrap(JSVM_Env env, @@ -2204,7 +2294,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_Unwrap(JSVM_Env env, void** result); /** - * @brief 使用OH_JSVM_Wrap()检索先前封装在JavaScript对象js_object中的native实例并移除封装。 + * @brief 使用OH_JSVM_Wrap()检索先前封装在JavaScript对象——js_object中的native实例并移除封装。 * 如果finalize回调与封装相关联，则当JavaScript对象被垃圾回收时将不再调用它。 * * @param env 调用JSVM-API的环境。 @@ -2212,6 +2302,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_Unwrap(JSVM_Env env, * @param result 指向封装的native实例的指针。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_INVALID_ARG } 表示传入的参数不合法。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_RemoveWrap(JSVM_Env env, @@ -2336,6 +2428,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_MemoryPressureNotification(JSVM_Env env, * @param promise 与延迟对象关联的JavaScript Promise。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 11 */ @@ -2354,6 +2447,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreatePromise(JSVM_Env env, * @param resolution 用来解决Promise的值。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_ResolveDeferred(JSVM_Env env, @@ -2371,6 +2466,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_ResolveDeferred(JSVM_Env env, * @param rejection 用来拒绝Promise的值。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_RejectDeferred(JSVM_Env env, @@ -2392,18 +2489,18 @@ JSVM_EXTERN JSVM_Status OH_JSVM_IsPromise(JSVM_Env env, bool* isPromise); /** - * @brief 注册处理 Promise 兑现/拒绝的回调函数。 + * @brief 注册 处理Promise兑现/拒绝的 回调函数。 * @param env 调用 JSVM-API 的环境。 * @param promise 需要注册回调的 promise。 * @param onFulfilled 该函数在 promise 兑现后调用。 * @param onRejected 该函数在 promise 拒绝后调用。 * @param result 输出参数，返回 promise 调用 then/catch 接口后生成的新的 promise。 * @return 返回执行状态码。 - * {@link JSVM_OK } 表示执行成功。 \n - * {@link JSVM_INVALID_ARG } 如果 env 或 promise 为空，或 onFulfilled 和 onRejected 同时为空。 \n - * {@link JSVM_INVALID_TYPE } 如果 promise 非 JS 的 Promise 类型，或 onFulfilled、onRejected 非 JS 的 Function 类型。 \n - * {@link JSVM_PENDING_EXCEPTION} 如果存在 JS 异常待处理。 \n - * {@link JSVM_GENERIC_FAILURE} 如果 API 执行错误。 \n + * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_INVALID_ARG } 如果 env 或 promise 为空，或 onFulfilled 和 onRejected 同时为空。\n + * {@link JSVM_INVALID_TYPE } 如果 promise 非 JS 的 Promise 类型，或 onFulfilled、onRejected 非 JS 的 Function 类型。\n + * {@link JSVM_PENDING_EXCEPTION} 如果存在 JS 异常待处理。\n + * {@link JSVM_GENERIC_FAILURE} 如果 API 执行错误。\n * * @since 18 */ @@ -2423,6 +2520,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_PromiseRegisterHandler(JSVM_Env env, * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_STRING_EXPECTED } 表示传入的参数不是string类型。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_JsonParse(JSVM_Env env, @@ -2438,6 +2536,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_JsonParse(JSVM_Env env, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * @since 11 */ JSVM_EXTERN JSVM_Status OH_JSVM_JsonStringify(JSVM_Env env, @@ -2526,6 +2625,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_TakeHeapSnapshot(JSVM_VM vm, * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 12 */ JSVM_EXTERN JSVM_Status OH_JSVM_OpenInspector(JSVM_Env env, @@ -2538,6 +2638,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_OpenInspector(JSVM_Env env, * @param env 调用JSVM-API的环境。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n + * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 12 */ JSVM_EXTERN JSVM_Status OH_JSVM_CloseInspector(JSVM_Env env); @@ -2547,9 +2649,10 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CloseInspector(JSVM_Env env); * 发送Runtime.runIfWaitingForDebugger命令。 * * @param env 调用JSVM-API的环境。 - * @param breakNextLine 是否在下一行JavaScript代码中中断。传递“是”，后续将暂停在运行下一行JS代码时，继续运行需要开发者通过调试器的调试按钮控制JS的执行。 + * @param breakNextLine 是否在下一行JavaScript代码中中断。breakNextLine为true将暂停运行下一行JS代码，开发者需要通过调试器的调试按钮控制JS继续执行。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 12 */ @@ -2557,7 +2660,8 @@ JSVM_EXTERN JSVM_Status OH_JSVM_WaitForDebugger(JSVM_Env env, bool breakNextLine); /** - * @brief 定义一个具有给定类名、构造函数、属性和回调处理程序的JavaScript类属性操作包括getter、setter、deleter、enumerator等，并作为函数回调进行调用。 + * @brief 定义一个具有给定类名、构造函数、属性和回调处理程序的JavaScript类， + * 属性操作包括getter、setter、deleter、enumerator等，并作为函数回调进行调用。 * * @param env 调用JSVM-API的环境。 * @param utf8name JavaScript类构造函数的名称。 @@ -2571,6 +2675,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_WaitForDebugger(JSVM_Env env, * @param result 表示JavaScript类的构造函数的JSVM_Value。 * @return 返回执行状态码 JSVM_Status。 * {@link JSVM_OK } 表示执行成功。\n + * {@link JSVM_PENDING_EXCEPTION } 表示执行的过程中产生了JS异常。\n * {@link JSVM_GENERIC_FAILURE } 表示有未知的原因导致执行失败。\n * @since 12 */ @@ -2775,7 +2880,7 @@ JSVM_Status JSVM_CDECL OH_JSVM_IsConstructor(JSVM_Env env, bool* isConstructor); /** - * @brief 此API返回与输入对应的正则表达式的JavaScript值。 + * @brief 此API返回与输入的JavaScript字符串对应的正则表达式对象。 * 接口可能会抛出异常。 * * @param env 调用JSVM-API的环境。 @@ -2907,7 +3012,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_CreateFunctionWithScript(JSVM_Env env, JSVM_Value* result); /** - * @brief 启动虚拟机内任务队列的运行。这个任务队列可以通过外部事件循环来执行。 + * @brief 启动虚拟机内任务队列，这个任务队列可以通过外部事件循环执行。 * * @param vm 启动任务队列的虚拟机实例。 * @param result 表示任务队列是否成功启动。 @@ -2941,7 +3046,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_PerformMicrotaskCheckpoint(JSVM_VM vm); JSVM_EXTERN JSVM_Status OH_JSVM_RetainScript(JSVM_Env env, JSVM_Script script); /** - * @brief 此函数释放由OH_JSVM_RetainScript保留的脚本，释放后应避免对传入 script 的再次使用. + * @brief 释放由 OH_JSVM_RetainScript 保留的脚本，释放后应避免对传入 script 的再次使用. * * @param env 调用该API的环境. * @param script 包含要释放的脚本的JavaScript字符串. @@ -2953,7 +3058,7 @@ JSVM_EXTERN JSVM_Status OH_JSVM_RetainScript(JSVM_Env env, JSVM_Script script); JSVM_EXTERN JSVM_Status OH_JSVM_ReleaseScript(JSVM_Env env, JSVM_Script script); /** - * @brief 此函数打开一个命名为传入 name 的 inspector，为其打开对应 pid 的 unix domain 端口. + * @brief 打开一个名为 name 的 inspector，为其打开对应 pid 的 unix domain 端口. * * @param env 调用该API的环境. * @param pid 用于标识 inspector 连接的进程ID. @@ -3301,11 +3406,13 @@ JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolIterator(JSVM_Env env, JSVM_Value* resu * * @since 18 */ -JSVM_EXTERN JSVM_Status OH_JSVM_TraceStart(size_t count, const JSVM_TraceCategory* categories, - const char* tag, size_t eventsCount); +JSVM_EXTERN JSVM_Status OH_JSVM_TraceStart(size_t count, + const JSVM_TraceCategory* categories, + const char* tag, + size_t eventsCount); /** - * @brief 对所有 JSVM 运行时，结束采集指定 Trace 类别的信息。(线程不安全) + * @brief 对所有 JSVM 运行时，停止采集指定 Trace 类别的信息。(线程不安全) * * @param stream 输出流回调函数，实现接收 Trace 数据功能。 * @param streamData 的输出流指针，用于辅助输出流回调函数进行数据输出。 @@ -3429,9 +3536,9 @@ JSVM_EXTERN JSVM_Status OH_JSVM_SetHandlerForPromiseReject(JSVM_VM vm, * @param options 传入的用于定义class的选项数组。 * @param result 表示类的构造函数的JSVM_Value。 * @return 返回执行状态码 JSVM_Status - * {@link JSVM_OK } 表示执行成功。 \n + * {@link JSVM_OK } 表示执行成功。\n * {@link JSVM_INVALID_ARG } 表示传入的指针参数里面存在空指针。\n - * {@link JSVM_GENERIC_FAILURE} 表示传入的utf8name | constructor | properties无效，导致执行失败。 \n + * {@link JSVM_GENERIC_FAILURE} 表示传入的utf8name | constructor | properties无效，导致执行失败。\n * @since 18 */ JSVM_EXTERN JSVM_Status OH_JSVM_DefineClassWithOptions(JSVM_Env env, diff --git a/zh-cn/native_sdk/ark_runtime/jsvm/jsvm_types.h b/zh-cn/native_sdk/ark_runtime/jsvm/jsvm_types.h index 824bb595..71162d39 100644 --- a/zh-cn/native_sdk/ark_runtime/jsvm/jsvm_types.h +++ b/zh-cn/native_sdk/ark_runtime/jsvm/jsvm_types.h @@ -46,9 +46,32 @@ #include // NOLINT(modernize-deprecated-headers) #if !defined __cplusplus || (defined(_MSC_VER) && _MSC_VER < 1900) +/** + * @brief 为uint16_t创建一个别名——char16_t + * + * 这段代码的核心目的是确保 char16_t 这个类型在所有目标编译环境中都可用，即使在一些不支持它的旧环境里。 + * char16_t 是 C++11 标准中引入的一个新的基本数据类型，专门用于存储16位字符，通常用来表示UTF-16编码的字符。 + * + * 如果编译器本身不认识char16_t，手动创建一个底层实现是16位无符号的整数类型。 + * 前置生效条件为：当前编译器——非C++编译器编译 || 是微软Visual C++编译器且版本早于Visual Studio 2015（不含）。 + * + * @since 11 + */ typedef uint16_t char16_t; #endif +/** + * @brief 为不同平台统一函数约定调用（Calling Convention）的宏 + * + * 如果在 Windows 上，JSVM_CDECL 宏会被展开为 __cdecl。 + * __cdecl是 C/C++ 语言在 x86 架构上的默认调用约定。它的主要特点是：参数从右到左压入栈、调用者 (caller) 负责清理栈。 + * 虽然 __cdecl 是默认的，但在 Windows API 编程中，还存在其他CC，如 __stdcall（被调用者清理栈，Win32 API常用）和 __fastcall（部分参数用寄存器传递）。 + * 通过显式指定__cdecl，确保即使项目全局编译设置被修改为其他约定，被这个宏修饰的函数依然可以保持 __cdecl 约定，从而避免不匹配问题。 + * + * 在大多数非 Windows 系统（如遵循 System V ABI 的 Linux/macOS）上，通常只有一种标准的调用约定，无须指定JSVM_CDECL。 + * + * @since 11 + */ #ifndef JSVM_CDECL #ifdef _WIN32 #define JSVM_CDECL __cdecl @@ -618,7 +641,7 @@ typedef struct { typedef JSVM_PropertyHandlerConfigurationStruct* JSVM_PropertyHandlerCfg; /** - * @brief Source code information. + * @brief 某段JavaScript代码的原始信息，如sourceMap路径、源文件名、源文件中的起始行/列号等. * * @since 12 */ -- Gitee