1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef NAPI_ARK_INTEROP_NAPI_H 17 #define NAPI_ARK_INTEROP_NAPI_H 18 19 #include <cstdint> 20 #include <cstddef> 21 #include <iostream> 22 23 #include "ark_interop_macro.h" 24 25 DECL_START 26 27 /** 28 * es6 types (corresponds to typeof) 29 */ 30 typedef enum { 31 N_UNDEFINED, 32 N_NULL, 33 N_NUMBER, 34 N_BOOL, 35 N_BIGINT, 36 N_STRING, 37 N_SYMBOL, 38 N_OBJECT, 39 N_FUNCTION, 40 N_EXTERNAL, 41 } ARKTS_ValueType; 42 43 /** 44 * js object property descriptor attribute 45 */ 46 typedef enum { 47 N_WRITABLE = 0x1, 48 N_ENUMERABLE = 0x2, 49 N_CONFIGURABLE = 0x4, 50 } ARKTS_PropertyFlag; 51 52 typedef struct ARKTS_Value_* ARKTS_Value; 53 typedef struct ARKTS_Env_* ARKTS_Env; 54 typedef struct ARKTS_CallInfo_* ARKTS_CallInfo; 55 typedef struct ARKTS_Result_* ARKTS_Result; 56 /** 57 * be caution: ARKTS_Promise is not ARKTS_Value, you may not cast ARKTS_Promise to ARKTS_Value. 58 */ 59 typedef struct ARKTS_Promise_* ARKTS_Promise; 60 typedef struct ARKTS_Scope_* ARKTS_Scope; 61 typedef struct ARKTS_Global_* ARKTS_Global; 62 typedef struct ARKTS_Engine_* ARKTS_Engine; 63 64 typedef ARKTS_Result (*ARKTS_Callback)(ARKTS_CallInfo); 65 typedef ARKTS_Value (*ARKTS_ModuleExporter)(ARKTS_Env env, ARKTS_Value); 66 67 EXPORT ARKTS_Value ARKTS_GetGlobalConstant(ARKTS_Env env); 68 EXPORT uint64_t ARKTS_GetPosixThreadId(); 69 70 EXPORT ARKTS_ValueType ARKTS_GetValueType(ARKTS_Env env, ARKTS_Value src); 71 EXPORT bool ARKTS_StrictEqual(ARKTS_Env env, ARKTS_Value a, ARKTS_Value b); 72 73 EXPORT double ARKTS_GetValueNumber(ARKTS_Value value); 74 EXPORT bool ARKTS_IsNumber(ARKTS_Value value); 75 EXPORT ARKTS_Value ARKTS_CreateF64(double value); 76 EXPORT ARKTS_Value ARKTS_CreateI32(int32_t value); 77 78 EXPORT int32_t ARKTS_GetValueUtf8(ARKTS_Env env, ARKTS_Value value, int32_t capacity, char* buffer); 79 EXPORT int32_t ARKTS_GetValueUtf8Size(ARKTS_Env env, ARKTS_Value value); 80 EXPORT ARKTS_Value ARKTS_CreateUtf8(ARKTS_Env env, const char* value, int32_t size); 81 /** 82 * the result requires manually free, use ARKTS_FreeCString 83 */ 84 EXPORT const char* ARKTS_GetValueCString(ARKTS_Env env, ARKTS_Value value); 85 EXPORT void ARKTS_FreeCString(const char* src); 86 EXPORT bool ARKTS_IsString(ARKTS_Env env, ARKTS_Value value); 87 88 typedef struct { 89 bool isCompressed; 90 uint32_t length; 91 } ARKTS_StringInfo; 92 EXPORT ARKTS_StringInfo ARKTS_GetStringInfo(ARKTS_Env env, ARKTS_Value value); 93 EXPORT void ARKTS_StringCopy(ARKTS_Env env, ARKTS_Value value, void* dst, uint32_t length); 94 EXPORT ARKTS_Value ARKTS_CreateString(ARKTS_Env env, bool isCompressed, uint32_t length, const void* data); 95 96 EXPORT ARKTS_Value ARKTS_CreateFunc(ARKTS_Env env, int64_t lambdaId); 97 /** 98 * logically equals to typeof(value) == "function" 99 */ 100 EXPORT bool ARKTS_IsCallable(ARKTS_Env env, ARKTS_Value value); 101 102 EXPORT bool ARKTS_IsClass(ARKTS_Env env, ARKTS_Value value); 103 EXPORT ARKTS_Value ARKTS_CreateClass(ARKTS_Env env, int64_t lambdaId, ARKTS_Value super); 104 EXPORT ARKTS_Value ARKTS_GetPrototype(ARKTS_Env env, ARKTS_Value value); 105 EXPORT bool ARKTS_InstanceOf(ARKTS_Env env, ARKTS_Value object, ARKTS_Value clazz); 106 107 EXPORT ARKTS_Env ARKTS_GetCallEnv(ARKTS_CallInfo info); 108 EXPORT uint32_t ARKTS_GetArgCount(ARKTS_CallInfo info); 109 EXPORT ARKTS_Value ARKTS_GetArg(ARKTS_CallInfo info, uint32_t index); 110 EXPORT ARKTS_Value ARKTS_GetThisArg(ARKTS_CallInfo info); 111 112 EXPORT ARKTS_Value ARKTS_Call(ARKTS_Env env, ARKTS_Value func, ARKTS_Value thisArg, 113 int32_t numArgs, ARKTS_Value args[]); 114 EXPORT ARKTS_Value ARKTS_New(ARKTS_Env env, ARKTS_Value clazz, int32_t numArgs, ARKTS_Value args[]); 115 116 EXPORT ARKTS_Value ARKTS_CreateNull(); 117 EXPORT bool ARKTS_IsNull(ARKTS_Value value); 118 EXPORT ARKTS_Value ARKTS_CreateUndefined(); 119 EXPORT bool ARKTS_IsUndefined(ARKTS_Value value); 120 EXPORT ARKTS_Value ARKTS_CreateBool(bool value); 121 EXPORT bool ARKTS_IsBool(ARKTS_Value value); 122 EXPORT bool ARKTS_GetValueBool(ARKTS_Value value); 123 124 EXPORT ARKTS_Value ARKTS_CreateObject(ARKTS_Env env); 125 /** 126 * js types excludes [number, boolean, null, undefined] are JSHeapObject 127 */ 128 EXPORT bool ARKTS_IsHeapObject(ARKTS_Value value); 129 130 // only available for JSObject, any other heap object(like JSArray, JSProxy...) supposed to call it's type-specific api 131 EXPORT bool ARKTS_IsObject(ARKTS_Env env, ARKTS_Value value); 132 EXPORT bool ARKTS_HasOwnProperty(ARKTS_Env env, ARKTS_Value jobj, ARKTS_Value jkey); 133 EXPORT ARKTS_Value ARKTS_EnumOwnProperties(ARKTS_Env env, ARKTS_Value jobj); 134 EXPORT void ARKTS_DefineOwnProperty(ARKTS_Env env, ARKTS_Value jobj, ARKTS_Value jkey, 135 ARKTS_Value jvalue, ARKTS_PropertyFlag attrs); 136 EXPORT bool ARKTS_DefineOwnPropertyV2(ARKTS_Env env, ARKTS_Value jobj, ARKTS_Value jkey, ARKTS_Value jvalue, 137 ARKTS_PropertyFlag attrs); 138 139 typedef struct ARKTS_Accessor_ { 140 ARKTS_Value getter; 141 ARKTS_Value setter; 142 ARKTS_PropertyFlag attrs; 143 } ARKTS_Accessor; 144 145 EXPORT void ARKTS_DefineAccessors(ARKTS_Env env, ARKTS_Value jobj, ARKTS_Value jkey, ARKTS_Accessor accessor); 146 EXPORT bool ARKTS_DefineAccessorsV2(ARKTS_Env env, ARKTS_Value jobj, ARKTS_Value jkey, ARKTS_Accessor accessor); 147 EXPORT void ARKTS_SetProperty(ARKTS_Env env, ARKTS_Value jobj, ARKTS_Value jkey, ARKTS_Value jvalue); 148 EXPORT ARKTS_Value ARKTS_GetProperty(ARKTS_Env env, ARKTS_Value jobj, ARKTS_Value jkey); 149 150 EXPORT ARKTS_Value ARKTS_CreateArray(ARKTS_Env env, uint32_t size); 151 EXPORT ARKTS_Value ARKTS_CreateArrayWithInit(ARKTS_Env env, uint32_t size, ARKTS_Value data[]); 152 EXPORT uint32_t ARKTS_GetArrayLength(ARKTS_Env env, ARKTS_Value array); 153 EXPORT void ARKTS_SetElement(ARKTS_Env env, ARKTS_Value array, uint32_t index, ARKTS_Value value); 154 EXPORT ARKTS_Value ARKTS_GetElement(ARKTS_Env env, ARKTS_Value array, uint32_t index); 155 EXPORT bool ARKTS_IsArray(ARKTS_Env env, ARKTS_Value value); 156 157 EXPORT ARKTS_Global ARKTS_CreateGlobal(ARKTS_Env env, ARKTS_Value value); 158 EXPORT bool ARKTS_GlobalIsAlive(ARKTS_Env env, ARKTS_Global global); 159 EXPORT ARKTS_Value ARKTS_GetGlobalValue(ARKTS_Global global); 160 EXPORT void ARKTS_DisposeGlobal(ARKTS_Env env, ARKTS_Global global); 161 EXPORT void ARKTS_DisposeGlobalSync(ARKTS_Env env, ARKTS_Global global); 162 163 EXPORT ARKTS_Value ARKTS_CreateExternal(ARKTS_Env env, void* data); 164 EXPORT bool ARKTS_IsExternal(ARKTS_Env env, ARKTS_Value value); 165 EXPORT void* ARKTS_GetExternalData(ARKTS_Env env, ARKTS_Value value); 166 167 EXPORT ARKTS_Value ARKTS_CreateSymbol(ARKTS_Env env, const char* description, int32_t length); 168 EXPORT bool ARKTS_IsSymbol(ARKTS_Env env, ARKTS_Value value); 169 EXPORT const char* ARKTS_GetSymbolDesc(ARKTS_Env env, ARKTS_Value value); 170 171 EXPORT ARKTS_Engine ARKTS_CreateEngine(); 172 EXPORT void* ARKTS_GetNAPIEnv(ARKTS_Engine engine); 173 EXPORT void ARKTS_DestroyEngine(ARKTS_Engine engine); 174 EXPORT ARKTS_Env ARKTS_GetContext(ARKTS_Engine engine); 175 EXPORT ARKTS_Engine ARKTS_CreateEngineWithNewThread(); 176 EXPORT uint64_t ARKTS_GetThreadIdOfEngine(ARKTS_Engine engine); 177 178 EXPORT bool ARKTS_LoadEntryFromAbc(ARKTS_Engine engine, const char* filePath, const char* entryPoint, 179 bool forceReload); 180 EXPORT ARKTS_Value ARKTS_ImportFromEntry(ARKTS_Engine engine, const char* entryPoint, const char* importName); 181 182 EXPORT ARKTS_Value ARKTS_Require(ARKTS_Env env, const char* target, bool isNativeModule, bool isAppModule, 183 const char* relativePath); 184 185 /** 186 * promise in js and native are in different forms, 187 * ARKTS_Promise the native form, ARKTS_Value is the js form, never cast one to another 188 * the interface returns both forms, native ARKTS_Promise returns by params 'out', 189 * ARKTS_Promise won't be collected until ARKTS_PromiseCapabilityResolve or ARKTS_PromiseCapabilityReject 190 */ 191 EXPORT ARKTS_Promise ARKTS_CreatePromiseCapability(ARKTS_Env env); 192 EXPORT ARKTS_Value ARKTS_GetPromiseFromCapability(ARKTS_Env env, ARKTS_Promise prom); 193 EXPORT void ARKTS_PromiseCapabilityResolve(ARKTS_Env env, ARKTS_Promise prom, ARKTS_Value result); 194 EXPORT void ARKTS_PromiseCapabilityReject(ARKTS_Env env, ARKTS_Promise prom, ARKTS_Value result); 195 EXPORT bool ARKTS_IsPromise(ARKTS_Env env, ARKTS_Value value); 196 EXPORT ARKTS_Value ARKTS_PromiseThen(ARKTS_Env env, ARKTS_Value prom, ARKTS_Value onFulfilled, 197 ARKTS_Value onRejected); 198 EXPORT ARKTS_Value ARKTS_PromiseCatch(ARKTS_Env env, ARKTS_Value prom, ARKTS_Value callback); 199 200 EXPORT void ARKTS_CreateAsyncTask(ARKTS_Env env, int64_t callbackId); 201 202 /** 203 * if native func call js function, GC would be triggered and objects created by native would be collected. 204 * objects created in scope will keep alive 205 * scope will close by ARKTS_Return 206 */ 207 EXPORT ARKTS_Scope ARKTS_OpenScope(ARKTS_Env env); 208 EXPORT void ARKTS_CloseScope(ARKTS_Env env, ARKTS_Scope scope); 209 EXPORT ARKTS_Result ARKTS_Return(ARKTS_Env env, ARKTS_Scope scope, ARKTS_Value value); 210 211 /** 212 * if error supposed to be catch by js, returns asap, 213 * some native api may lead to native exception handling procedural 214 */ 215 EXPORT void ARKTS_Throw(ARKTS_Env env, ARKTS_Value error); 216 217 EXPORT ARKTS_Value ARKTS_CreateArrayBuffer(ARKTS_Env env, int32_t); 218 EXPORT ARKTS_Value ARKTS_CreateArrayBufferWithData(ARKTS_Env env, void* buffer, int32_t length, 219 int64_t finalizerHint); 220 EXPORT bool ARKTS_IsArrayBuffer(ARKTS_Env env, ARKTS_Value value); 221 EXPORT int32_t ARKTS_GetArrayBufferLength(ARKTS_Env env, ARKTS_Value value); 222 EXPORT void* ARKTS_GetArrayBufferRawPtr(ARKTS_Env env, ARKTS_Value value); 223 EXPORT int32_t ARKTS_ArrayBufferReadBytes(ARKTS_Env env, ARKTS_Value buffer, void* dest, int32_t count); 224 225 EXPORT ARKTS_Value ARKTS_CreateBigInt(ARKTS_Env env, int64_t value); 226 EXPORT ARKTS_Value ARKTS_CreateBigIntWithBytes(ARKTS_Env env, bool isNegative, int64_t size, const uint8_t bytes[]); 227 EXPORT bool ARKTS_IsBigInt(ARKTS_Env env, ARKTS_Value value); 228 EXPORT int64_t ARKTS_BigIntGetByteSize(ARKTS_Env env, ARKTS_Value value); 229 EXPORT void ARKTS_BigIntReadBytes(ARKTS_Env env, ARKTS_Value value, bool* isNegative, 230 int64_t byteCount, uint8_t bytes[]); 231 // @deprecated 232 EXPORT void ARKTS_InitEventHandle(ARKTS_Env env); 233 234 EXPORT void* ARKTS_GetGlobalNapiEnv(ARKTS_Env env); 235 236 EXPORT void ARKTS_UpdateStackInfo(unsigned long long vmAddress, void *subStackInfo, unsigned int opKind); 237 238 EXPORT void ARKTS_GlobalSetWeak(ARKTS_Env env, ARKTS_Global global); 239 EXPORT void ARKTS_GlobalClearWeak(ARKTS_Env env, ARKTS_Global global); 240 EXPORT ARKTS_Value ARKTS_GlobalToValue(ARKTS_Env env, ARKTS_Global global); 241 EXPORT ARKTS_Global ARKTS_GlobalFromValue(ARKTS_Env env, ARKTS_Value value); 242 EXPORT ARKTS_Value ARKTS_CreateCycleFreeFunc(ARKTS_Env env, int64_t id); 243 EXPORT ARKTS_Value ARKTS_CreateCycleFreeExtern(ARKTS_Env env, int64_t id); 244 typedef struct { 245 ARKTS_Value (*funcInvoker)(ARKTS_CallInfo callInfo, int64_t id); 246 void (*refRelease)(int64_t id); 247 } ARKTS_CycleFreeCallback; 248 EXPORT void ARKTS_RegisterCycleFreeCallback(ARKTS_CycleFreeCallback callback); 249 EXPORT ARKTS_Value ARKTS_GetExceptionAndClear(ARKTS_Env env); 250 251 DECL_END 252 253 #endif //NAPI_ARK_INTEROP_NAPI_H 254