代码拉取完成，页面将自动刷新
同步操作将从 OpenHarmony/interface_sdk_c 强制同步，此操作会覆盖自 Fork 仓库以来所做的任何修改，且无法恢复！！！
确定后同步将在后台操作，完成时将刷新页面，请耐心等待。
/*
* Copyright (c) 2021 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef ARK_RUNTIME_JSVM_JSVM_H
#define ARK_RUNTIME_JSVM_JSVM_H
/**
* @addtogroup JSVM
* @{
*
* @brief Provides the standard JavaScript engine capabilities.
*
* Provides API to Provide independent, standard, and complete JavaScript engine capabilities for developers,
* including managing the engine lifecycle, compiling and running JS code, implementing JS/C++ cross language calls,
* and taking snapshots.
*
* @since 11
*/
/**
* @file jsvm.h
*
* @brief Provides the JSVM API define.
*
* Provides API to Provide independent, standard, and complete JavaScript engine capabilities for developers,
* including managing the engine lifecycle, compiling and running JS code, implementing JS/C++ cross language calls,
* and taking snapshots.
* @library libjsvm.so
* @syscap SystemCapability.ArkCompiler.JSVM
* @since 11
*/
// This file needs to be compatible with C compilers.
#include <stdbool.h> // NOLINT(modernize-deprecated-headers)
#include <stddef.h> // NOLINT(modernize-deprecated-headers)
// Use INT_MAX, this should only be consumed by the pre-processor anyway.
#define JSVM_VERSION_EXPERIMENTAL 2147483647
#ifndef JSVM_VERSION
#ifdef JSVM_EXPERIMENTAL
#define JSVM_VERSION JSVM_VERSION_EXPERIMENTAL
#else
// The baseline version for JSVM-API.
// The JSVM_VERSION controls which version will be used by default when
// compilling a native addon. If the addon developer specifically wants to use
// functions available in a new version of JSVM-API that is not yet ported in all
// LTS versions, they can set JSVM_VERSION knowing that they have specifically
// depended on that version.
#define JSVM_VERSION 8
#endif
#endif
#include "jsvm_types.h"
#ifndef JSVM_EXTERN
#ifdef _WIN32
/**
* @brief externally visible.
*
* @since 11
*/
#define JSVM_EXTERN __declspec(dllexport)
#elif defined(__wasm__)
#define JSVM_EXTERN \
__attribute__((visibility("default"))) \
__attribute__((__import_module__("jsvm")))
#else
#define JSVM_EXTERN __attribute__((visibility("default")))
#endif
#endif
/**
* @brief auto length.
*
* @since 11
*/
#define JSVM_AUTO_LENGTH SIZE_MAX
#ifdef __cplusplus
#define EXTERN_C_START extern "C" {
#define EXTERN_C_END }
#else
#define EXTERN_C_START
#define EXTERN_C_END
#endif
EXTERN_C_START
/**
* @brief Init a JavaScript vm.
*
* @param options: The options for initialize the JavaScript VM.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_Init(const JSVM_InitOptions* options);
/**
* @brief This API create a new VM instance.
*
* @param options: The options for create the VM instance.
* @param result: The new VM instance.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateVM(const JSVM_CreateVMOptions* options,
JSVM_VM* result);
/**
* @brief Destroys VM instance.
*
* @param vm: The VM instance to be Destroyed.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_DestroyVM(JSVM_VM vm);
/**
* @brief This API open a new VM scope for the VM instance.
*
* @param vm: The VM instance to open scope for.
* @param result: The new VM scope.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_OpenVMScope(JSVM_VM vm,
JSVM_VMScope* result);
/**
* @brief This function close the VM scope for the VM instance.
*
* @param vm: The VM instance to close scope for.
* @param scope: The VM scope to be closed.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CloseVMScope(JSVM_VM vm,
JSVM_VMScope scope);
/**
* @brief This function create a new environment with optional properties for the context of the new environment.
*
* @param vm: The VM instance that the env will be created in.
* @param propertyCount: The number of elements in the properties array.
* @param properties: The array of property descriptor.
* @param result: The new environment created.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateEnv(JSVM_VM vm,
size_t propertyCount,
const JSVM_PropertyDescriptor* properties,
JSVM_Env* result);
/**
* @brief This function create a new environment from the start snapshot of the vm.
*
* @param vm: The VM instance that the env will be created in.
* @param index: The index of the environment in the snapshot.
* @param result: The new environment created.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateEnvFromSnapshot(JSVM_VM vm,
size_t index,
JSVM_Env* result);
/**
* @brief This function destroys the environment.
*
* @param env: The environment to be destroyed.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_DestroyEnv(JSVM_Env env);
/**
* @brief This function open a new environment scope.
*
* @param env: The environment that the JSVM-API call is invoked under.
* @param result: The new environment scope.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_OpenEnvScope(JSVM_Env env,
JSVM_EnvScope* result);
/**
* @brief This function closes the environment scope of the environment.
*
* @param env: The environment that the JSVM-API call is invoked under.
* @param scope: The environment scope to be closed.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CloseEnvScope(JSVM_Env env,
JSVM_EnvScope scope);
/**
* @brief This function compiles a string of JavaScript code and returns the compiled script.
*
* @param env: The environment that the JSVM-API call is invoked under.
* @param script: A JavaScript string containing the script yo be compiled.
* @param cachedData: Optional code cache data for the script.
* @param cacheDataLength: The length of cachedData array.
* @param eagerCompile: Whether to compile the script eagerly.
* @param cacheRejected: Whether the code cache rejected by compilation.
* @param result: The compiled script.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CompileScript(JSVM_Env env,
JSVM_Value script,
const uint8_t* cachedData,
size_t cacheDataLength,
bool eagerCompile,
bool* cacheRejected,
JSVM_Script* result);
/**
* @brief This function creates code cache for the compiled script.
*
* @param env: The environment that the JSVM-API call is invoked under.
* @param script: A compiled script to create code cache for.
* @param data: The data of the code cache.
* @param length: The length of the code cache data.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateCodeCache(JSVM_Env env,
JSVM_Script script,
const uint8_t** data,
size_t* length);
/**
* @brief This function executes a string of JavaScript code and returns its result with the following caveats:
* Unlike eval, this function does not allow the script to access the current lexical scope, and therefore also
* does not allow to access the module scope, meaning that pseudo-globals such as require will not be available.
* The script can access the global scope. Function and var declarations in the script will be added to the
* global object. Variable declarations made using let and const will be visible globally, but will not be added
* to the global object.The value of this is global within the script.
*
* @param env: The environment that the API is invoked under.
* @param script: A JavaScript string containing the script to execute.
* @param result: The value resulting from having executed the script.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_RunScript(JSVM_Env env,
JSVM_Script script,
JSVM_Value* result);
/**
* @brief This API associates data with the currently running JSVM environment. data can later be retrieved
* using OH_JSVM_GetInstanceData().
*
* @param env: The environment that the JSVM-API call is invoked under.
* @param data: The data item to make available to bindings of this instance.
* @param finalizeCb: The function to call when the environment is being torn down. The function receives
* data so that it might free it. JSVM_Finalize provides more details.
* @param finalizeHint: Optional hint to pass to the finalize callback during collection.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_SetInstanceData(JSVM_Env env,
void* data,
JSVM_Finalize finalizeCb,
void* finalizeHint);
/**
* @brief This API retrieves data that was previously associated with the currently running JSVM environment
* via OH_JSVM_SetInstanceData(). If no data is set, the call will succeed and data will be set to NULL.
*
* @param env: The environment that the JSVM-API call is invoked under.
* @param data: The data item that was previously associated with the currently running JSVM environment by
* a call to OH_JSVM_SetInstanceData().
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetInstanceData(JSVM_Env env,
void** data);
/**
* @brief This API retrieves a JSVM_ExtendedErrorInfo structure with information about the last error that
* occurred.
*
* @param env: The environment that the JSVM-API call is invoked under.
* @param result: The JSVM_ExtendedErrorInfo structure with more information about the error.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetLastErrorInfo(JSVM_Env env,
const JSVM_ExtendedErrorInfo** result);
/**
* @brief This API throws the JavaScript value provided.
*
* @param env: The environment that the API is invoked under.
* @param error: The JavaScript value to be thrown.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_Throw(JSVM_Env env,
JSVM_Value error);
/**
* @brief This API throws a JavaScript Error with the text provided.
*
* @param env: The environment that the API is invoked under.
* @param code: Optional error code to be set on the error.
* @param msg: C string representing the text to be associated with the error.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ThrowError(JSVM_Env env,
const char* code,
const char* msg);
/**
* @brief This API throws a JavaScript TypeError with the text provided.
*
* @param env: The environment that the API is invoked under.
* @param code: Optional error code to be set on the error.
* @param msg: C string representing the text to be associated with the error.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ThrowTypeError(JSVM_Env env,
const char* code,
const char* msg);
/**
* @brief This API throws a JavaScript RangeError with the text provided.
*
* @param env: The environment that the API is invoked under.
* @param code: Optional error code to be set on the error.
* @param msg: C string representing the text to be associated with the error.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ThrowRangeError(JSVM_Env env,
const char* code,
const char* msg);
/**
* @brief This API throws a JavaScript SyntaxError with the text provided.
*
* @param env: The environment that the API is invoked under.
* @param code: Optional error code to be set on the error.
* @param msg: C string representing the text to be associated with the error.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ThrowSyntaxError(JSVM_Env env,
const char* code,
const char* msg);
/**
* @brief This API queries a JSVM_Value to check if it represents an error object.
*
* @param env: The environment that the API is invoked under.
* @param value: The JSVM_Value to be checked.
* @param result: Boolean value that is set to true if JSVM_Value represents an error,
* false otherwise.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsError(JSVM_Env env,
JSVM_Value value,
bool* result);
/**
* @brief This API returns a JavaScript Error with the text provided.
*
* @param env: The environment that the API is invoked under.
* @param code: Optional JSVM_Value with the string for the error code to be associated with the error.
* @param msg: JSVM_Value that references a JavaScript string to be used as the message for the Error.
* @param result: JSVM_Value representing the error created.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateError(JSVM_Env env,
JSVM_Value code,
JSVM_Value msg,
JSVM_Value* result);
/**
* @brief This API returns a JavaScript TypeError with the text provided.
*
* @param env: The environment that the API is invoked under.
* @param code: Optional JSVM_Value with the string for the error code to be associated with the error.
* @param msg: JSVM_Value that references a JavaScript string to be used as the message for the Error.
* @param result: JSVM_Value representing the error created.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypeError(JSVM_Env env,
JSVM_Value code,
JSVM_Value msg,
JSVM_Value* result);
/**
* @brief This API returns a JavaScript RangeError with the text provided.
*
* @param env: The environment that the API is invoked under.
* @param code: Optional JSVM_Value with the string for the error code to be associated with the error.
* @param msg: JSVM_Value that references a JavaScript string to be used as the message for the Error.
* @param result: JSVM_Value representing the error created.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateRangeError(JSVM_Env env,
JSVM_Value code,
JSVM_Value msg,
JSVM_Value* result);
/**
* @brief This API returns a JavaScript SyntaxError with the text provided.
*
* @param env: The environment that the API is invoked under.
* @param code: Optional JSVM_Value with the string for the error code to be associated with the error.
* @param msg: JSVM_Value that references a JavaScript string to be used as the message for the Error.
* @param result: JSVM_Value representing the error created.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateSyntaxError(JSVM_Env env,
JSVM_Value code,
JSVM_Value msg,
JSVM_Value* result);
/**
* @brief This API returns a JavaScript exception if one is pending, NULL otherwise.
*
* @param env: The environment that the API is invoked under.
* @param result: The exception if one is pending, NULL otherwise.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetAndClearLastException(JSVM_Env env,
JSVM_Value* result);
/**
* @brief This API returns true if an exception is pending, false otherwise.
*
* @param env: The environment that the API is invoked under.
* @param result: Boolean value that is set to true if an exception is pending.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsExceptionPending(JSVM_Env env,
bool* result);
/**
* @brief This API opens a new scope.
*
* @param env: The environment that the API is invoked under.
* @param result: JSVM_Value representing the new scope.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_OpenHandleScope(JSVM_Env env,
JSVM_HandleScope* result);
/**
* @brief This API closes the scope passed in. Scopes must be closed in the reverse
* order from which they were created.
*
* @param env: The environment that the API is invoked under.
* @param scope: JSVM_Value representing the scope to be closed.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CloseHandleScope(JSVM_Env env,
JSVM_HandleScope scope);
/**
* @brief This API opens a new scope from which one object can be promoted to the outer scope.
*
* @param env: The environment that the API is invoked under.
* @param result: JSVM_Value representing the new scope.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_OpenEscapableHandleScope(JSVM_Env env,
JSVM_EscapableHandleScope* result);
/**
* @brief This API closes the scope passed in. Scopes must be closed in the reverse order
* from which they were created.
*
* @param env: The environment that the API is invoked under.
* @param scope: JSVM_Value representing the scope to be closed.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CloseEscapableHandleScope(JSVM_Env env,
JSVM_EscapableHandleScope scope);
/**
* @brief This API promotes the handle to the JavaScript object so that it is valid for the lifetime
* of the outer scope. It can only be called once per scope. If it is called more than once an error
* will be returned.
*
* @param env: The environment that the API is invoked under.
* @param scope: JSVM_Value representing the current scope.
* @param escapee: JSVM_Value representing the JavaScript Object to be escaped.
* @param result: JSVM_Value representing the handle to the escaped Object in the outer scope.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_EscapeHandle(JSVM_Env env,
JSVM_EscapableHandleScope scope,
JSVM_Value escapee,
JSVM_Value* result);
/**
* @brief This API creates a new reference with the specified reference count to the value passed in.
*
* @param env: The environment that the API is invoked under.
* @param value: The JSVM_Value for which a reference is being created.
* @param initialRefcount: Initial reference count for the new reference.
* @param result: JSVM_Ref pointing to the new reference.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateReference(JSVM_Env env,
JSVM_Value value,
uint32_t initialRefcount,
JSVM_Ref* result);
/**
* @brief his API deletes the reference passed in.
*
* @param env: The environment that the API is invoked under.
* @param ref: JSVM_Ref to be deleted.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_DeleteReference(JSVM_Env env,
JSVM_Ref ref);
/**
* @brief his API increments the reference count for the reference passed in and
* returns the resulting reference count.
*
* @param env: The environment that the API is invoked under.
* @param ref: JSVM_Ref for which the reference count will be incremented.
* @param result: The new reference count.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ReferenceRef(JSVM_Env env,
JSVM_Ref ref,
uint32_t* result);
/**
* @brief This API decrements the reference count for the reference passed in and
* returns the resulting reference count.
*
* @param env: The environment that the API is invoked under.
* @param ref: JSVM_Ref for which the reference count will be decremented.
* @param result: The new reference count.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ReferenceUnref(JSVM_Env env,
JSVM_Ref ref,
uint32_t* result);
/**
* @brief If still valid, this API returns the JSVM_Value representing the
* JavaScript value associated with the JSVM_Ref. Otherwise, result will be NULL.
*
* @param env: The environment that the API is invoked under.
* @param ref: The JSVM_Ref for which the corresponding value is being requested.
* @param result: The JSVM_Value referenced by the JSVM_Ref.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetReferenceValue(JSVM_Env env,
JSVM_Ref ref,
JSVM_Value* result);
/**
* @brief This API returns a JSVM-API value corresponding to a JavaScript Array type.
*
* @param env: The environment that the API is invoked under.
* @param result: A JSVM_Value representing a JavaScript Array.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateArray(JSVM_Env env,
JSVM_Value* result);
/**
* @brief This API returns a JSVM-API value corresponding to a JavaScript Array type. The Array's length property
* is set to the passed-in length parameter. However, the underlying buffer is not guaranteed to be pre-allocated
* by the VM when the array is created. That behavior is left to the underlying VM implementation.
*
* @param env: The environment that the API is invoked under.
* @param length: The initial length of the Array.
* @param result: A JSVM_Value representing a JavaScript Array.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateArrayWithLength(JSVM_Env env,
size_t length,
JSVM_Value* result);
/**
* @brief This API returns a JSVM-API value corresponding to a JavaScript ArrayBuffer. ArrayBuffers are used to
* represent fixed-length binary data buffers. They are normally used as a backing-buffer for TypedArray objects.
* The ArrayBuffer allocated will have an underlying byte buffer whose size is determined by the length parameter
* that's passed in. The underlying buffer is optionally returned back to the caller in case the caller wants to
* directly manipulate the buffer. This buffer can only be written to directly from native code. To write to this
* buffer from JavaScript, a typed array or DataView object would need to be created.
*
* @param env: The environment that the API is invoked under.
* @param byteLength: The length in bytes of the array buffer to create.
* @param data: Pointer to the underlying byte buffer of the ArrayBuffer.data can optionally be ignored by passing NULL.
* @param result: A JSVM_Value representing a JavaScript Array.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateArraybuffer(JSVM_Env env,
size_t byteLength,
void** data,
JSVM_Value* result);
/**
* @brief This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification.
* This API allocates a JavaScript Date object.
*
* @param env: The environment that the API is invoked under.
* @param time: ECMAScript time value in milliseconds since 01 January, 1970 UTC.
* @param result: A JSVM_Value representing a JavaScript Date.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateDate(JSVM_Env env,
double time,
JSVM_Value* result);
/**
* @brief This API allocates a JavaScript value with external data attached to it. This is used to pass external
* data through JavaScript code, so it can be retrieved later by native code using OH_JSVM_GetValueExternal.
* The API adds a JSVM_Finalize callback which will be called when the JavaScript object just created has been garbage
* collected.The created value is not an object, and therefore does not support additional properties. It is considered
* a distinct value type: calling OH_JSVM_Typeof() with an external value yields JSVM_EXTERNAL.
*
* @param env: The environment that the API is invoked under.
* @param data: Raw pointer to the external data.
* @param finalizeCb: Optional callback to call when the external value is being collected. JSVM_Finalize provides
* more details.
* @param finalizeHint: Optional hint to pass to the finalize callback during collection.
* @param result: A JSVM_Value representing an external value.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateExternal(JSVM_Env env,
void* data,
JSVM_Finalize finalizeCb,
void* finalizeHint,
JSVM_Value* result);
/**
* @brief This API allocates a default JavaScript Object. It is the equivalent of doing new Object() in JavaScript.
*
* @param env: The environment that the API is invoked under.
* @param result: A JSVM_Value representing a JavaScript Object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateObject(JSVM_Env env,
JSVM_Value* result);
/**
* @brief This API creates a JavaScript symbol value from a UTF8-encoded C string.
*
* @param env: The environment that the API is invoked under.
* @param description: Optional JSVM_Value which refers to a JavaScript string to be set as the description
* for the symbol.
* @param result: A JSVM_Value representing a JavaScript symbol.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateSymbol(JSVM_Env env,
JSVM_Value description,
JSVM_Value* result);
/**
* @brief This API searches in the global registry for an existing symbol with the given description.
* If the symbol already exists it will be returned, otherwise a new symbol will be created in the registry.
*
* @param env: The environment that the API is invoked under.
* @param utf8description: UTF-8 C string representing the text to be used as the description for the symbol.
* @param length: The length of the description string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated.
* @param result: A JSVM_Value representing a JavaScript symbol.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_SymbolFor(JSVM_Env env,
const char* utf8description,
size_t length,
JSVM_Value* result);
/**
* @brief This API creates a JavaScript TypedArray object over an existing ArrayBuffer. TypedArray
* objects provide an array-like view over an underlying data buffer where each element has the
* same underlying binary scalar datatype.It's required that (length * size_of_element) + byte_offset should
* be <= the size in bytes of the array passed in. If not, a RangeError exception is raised.
*
* @param env: The environment that the API is invoked under.
* @param type: Scalar datatype of the elements within the TypedArray.
* @param length: Number of elements in the TypedArray.
* @param arraybuffer: ArrayBuffer underlying the typed array.
* @param byteOffset: The byte offset within the ArrayBuffer from which to start projecting the TypedArray.
* @param result: A JSVM_Value representing a JavaScript TypedArray
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypedarray(JSVM_Env env,
JSVM_TypedarrayType type,
size_t length,
JSVM_Value arraybuffer,
size_t byteOffset,
JSVM_Value* result);
/**
* @brief This API creates a JavaScript DataView object over an existing ArrayBuffer. DataView
* objects provide an array-like view over an underlying data buffer, but one which allows items
* of different size and type in the ArrayBuffer.It is required that byte_length + byte_offset is
* less than or equal to the size in bytes of the array passed in. If not, a RangeError exception
* is raised.
*
* @param env: The environment that the API is invoked under.
* @param length: Number of elements in the DataView.
* @param arraybuffer: ArrayBuffer underlying the DataView.
* @param byteOffset: The byte offset within the ArrayBuffer from which to start projecting the DataView.
* @param result:A JSVM_Value representing a JavaScript DataView.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateDataview(JSVM_Env env,
size_t length,
JSVM_Value arraybuffer,
size_t byteOffset,
JSVM_Value* result);
/**
* @brief This API is used to convert from the C int32_t type to the JavaScript number type.
*
* @param env: The environment that the API is invoked under.
* @param value: Integer value to be represented in JavaScript.
* @param result: A JSVM_Value representing a JavaScript number.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt32(JSVM_Env env,
int32_t value,
JSVM_Value* result);
/**
* @brief This API is used to convert from the C uint32_t type to the JavaScript number type.
*
* @param env: The environment that the API is invoked under.
* @param value: Unsigned integer value to be represented in JavaScript.
* @param result: A JSVM_Value representing a JavaScript number.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateUint32(JSVM_Env env,
uint32_t value,
JSVM_Value* result);
/**
* @brief This API is used to convert from the C int64_t type to the JavaScript number type.
*
* @param env: The environment that the API is invoked under.
* @param value: Integer value to be represented in JavaScript.
* @param result: A JSVM_Value representing a JavaScript number.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt64(JSVM_Env env,
int64_t value,
JSVM_Value* result);
/**
* @brief This API is used to convert from the C double type to the JavaScript number type.
*
* @param env: The environment that the API is invoked under.
* @param value: Double-precision value to be represented in JavaScript.
* @param result: A JSVM_Value representing a JavaScript number.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateDouble(JSVM_Env env,
double value,
JSVM_Value* result);
/**
* @brief This API converts the C int64_t type to the JavaScript BigInt type.
*
* @param env: The environment that the API is invoked under.
* @param value: Integer value to be represented in JavaScript.
* @param result: A JSVM_Value representing a JavaScript BigInt.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintInt64(JSVM_Env env,
int64_t value,
JSVM_Value* result);
/**
* @brief This API converts the C uint64_t type to the JavaScript BigInt type.
*
* @param env: The environment that the API is invoked under.
* @param value: Unsigned integer value to be represented in JavaScript.
* @param result: A JSVM_Value representing a JavaScript BigInt.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintUint64(JSVM_Env env,
uint64_t value,
JSVM_Value* result);
/**
* @brief This API converts an array of unsigned 64-bit words into a single BigInt value.
* The resulting BigInt is calculated as: (–1)sign_bit (words[0] × (264)0 + words[1] × (264)1 + …)
*
* @param env: The environment that the API is invoked under.
* @param signBit: Determines if the resulting BigInt will be positive or negative.
* @param wordCount: The length of the words array.
* @param words: An array of uint64_t little-endian 64-bit words.
* @param result: A JSVM_Value representing a JavaScript BigInt.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintWords(JSVM_Env env,
int signBit,
size_t wordCount,
const uint64_t* words,
JSVM_Value* result);
/**
* @brief This API creates a JavaScript string value from an ISO-8859-1-encoded C
* string. The native string is copied.
*
* @param env: The environment that the API is invoked under.
* @param str: Character buffer representing an ISO-8859-1-encoded string.
* @param length: The length of the string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated.
* @param result: A JSVM_Value representing a JavaScript string.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringLatin1(JSVM_Env env,
const char* str,
size_t length,
JSVM_Value* result);
/**
* @brief This API creates a JavaScript string value from a UTF16-LE-encoded C
* string. The native string is copied.
*
* @param env: The environment that the API is invoked under.
* @param str: Character buffer representing a UTF16-LE-encoded string.
* @param length: The length of the string in two-byte code units, or JSVM_AUTO_LENGTH
* if it is null-terminated.
* @param result: A JSVM_Value representing a JavaScript string.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf16(JSVM_Env env,
const char16_t* str,
size_t length,
JSVM_Value* result);
/**
* @brief This API creates a JavaScript string value from a UTF8-encoded C
* string. The native string is copied.
*
* @param env: The environment that the API is invoked under.
* @param str: Character buffer representing a UTF8-encoded string.
* @param length: The length of the string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated.
* @param result: A JSVM_Value representing a JavaScript string.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf8(JSVM_Env env,
const char* str,
size_t length,
JSVM_Value* result);
/**
* @brief This API returns the length of an array.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing the JavaScript Array whose length is being queried.
* @param result: uint32 representing length of the array.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetArrayLength(JSVM_Env env,
JSVM_Value value,
uint32_t* result);
/**
* @brief This API is used to retrieve the underlying data buffer of an ArrayBuffer and its length.
*
* @param env: The environment that the API is invoked under.
* @param arraybuffer: JSVM_Value representing the ArrayBuffer being queried.
* @param data: The underlying data buffer of the ArrayBuffer. If byte_length is 0, this may be NULL
* or any other pointer value.
* @param byteLength: Length in bytes of the underlying data buffer.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetArraybufferInfo(JSVM_Env env,
JSVM_Value arraybuffer,
void** data,
size_t* byteLength);
/**
* @brief This API returns the length of an array.
*
* @param env: The environment that the API is invoked under.
* @param object: JSVM_Value representing JavaScript Object whose prototype to return. This returns
* the equivalent of Object.getPrototypeOf (which is not the same as the function's prototype property).
* @param result: JSVM_Value representing prototype of the given object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetPrototype(JSVM_Env env,
JSVM_Value object,
JSVM_Value* result);
/**
* @brief This API returns various properties of a typed array.
*
* @param env: The environment that the API is invoked under.
* @param typedarray: JSVM_Value representing the TypedArray whose properties to query.
* @param type: Scalar datatype of the elements within the TypedArray.
* @param length: The number of elements in the TypedArray.
* @param data: The data buffer underlying the TypedArray adjusted by the byte_offset value so that it
* points to the first element in the TypedArray. If the length of the array is 0, this may be NULL or
* any other pointer value.
* @param arraybuffer: The ArrayBuffer underlying the TypedArray.
* @param byteOffset: The byte offset within the underlying native array at which the first element of
* the arrays is located. The value for the data parameter has already been adjusted so that data points
* to the first element in the array. Therefore, the first byte of the native array would be at data - byte_offset.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetTypedarrayInfo(JSVM_Env env,
JSVM_Value typedarray,
JSVM_TypedarrayType* type,
size_t* length,
void** data,
JSVM_Value* arraybuffer,
size_t* byteOffset);
/**
* @brief Any of the out parameters may be NULL if that property is unneeded.
* This API returns various properties of a DataView.
*
* @param env: The environment that the API is invoked under.
* @param dataview: JSVM_Value representing the DataView whose properties to query.
* @param bytelength: Number of bytes in the DataView.
* @param data: The data buffer underlying the DataView.
* If byte_length is 0, this may be NULL or any other pointer value.
* @param arraybuffer: ArrayBuffer underlying the DataView.
* @param byteOffset: The byte offset within the data buffer from which to start projecting the DataView.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetDataviewInfo(JSVM_Env env,
JSVM_Value dataview,
size_t* bytelength,
void** data,
JSVM_Value* arraybuffer,
size_t* byteOffset);
/**
* @brief Returns JSVM_OK if the API succeeded. If a non-date JSVM_Value is
* passed in it returns JSVM_date_expected.This API returns the C double
* primitive of time value for the given JavaScript Date.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing a JavaScript Date.
* @param result: Time value as a double represented as milliseconds
* since midnight at the beginning of 01 January, 1970 UTC.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetDateValue(JSVM_Env env,
JSVM_Value value,
double* result);
/**
* @brief This API returns the C boolean primitive equivalent of the given JavaScript Boolean.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript Boolean.
* @param result: C boolean primitive equivalent of the given JavaScript Boolean.
* @return Returns JSVM_OK if the API succeeded.
* If a non-boolean JSVM_Value is passed in it returns JSVM_BOOLEAN_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBool(JSVM_Env env,
JSVM_Value value,
bool* result);
/**
* @brief This API returns the C double primitive equivalent of the given JavaScript number.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript number.
* @param result: C double primitive equivalent of the given JavaScript number.
* @return Returns JSVM_OK if the API succeeded.
* If a non-number JSVM_Value is passed in it returns JSVM_NUMBER_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueDouble(JSVM_Env env,
JSVM_Value value,
double* result);
/**
* @brief This API returns the C int64_t primitive equivalent of the given JavaScript BigInt.
* If needed it will truncate the value, setting lossless to false.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript BigInt.
* @param result: C int64_t primitive equivalent of the given JavaScript BigInt.
* @param lossless: Indicates whether the BigInt value was converted losslessly.
* @return Returns JSVM_OK if the API succeeded. If a non-BigInt is passed in it returns JSVM_BIGINT_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintInt64(JSVM_Env env,
JSVM_Value value,
int64_t* result,
bool* lossless);
/**
* @brief This API returns the C uint64_t primitive equivalent of the given JavaScript BigInt.
* If needed it will truncate the value, setting lossless to false.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript BigInt.
* @param result: C uint64_t primitive equivalent of the given JavaScript BigInt.
* @param lossless: Indicates whether the BigInt value was converted losslessly.
* @return Returns JSVM_OK if the API succeeded. If a non-BigInt is passed in it returns JSVM_BIGINT_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintUint64(JSVM_Env env,
JSVM_Value value,
uint64_t* result,
bool* lossless);
/**
* @brief This API converts a single BigInt value into a sign bit, 64-bit little-endian array, and the number
* of elements in the array. signBit and words may be both set to NULL, in order to get only wordCount.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript BigInt.
* @param signBit: Integer representing if the JavaScript BigInt is positive or negative.
* @param wordCount: Must be initialized to the length of the words array. Upon return, it will be set to
* the actual number of words that would be needed to store this BigInt.
* @param words: Pointer to a pre-allocated 64-bit word array.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintWords(JSVM_Env env,
JSVM_Value value,
int* signBit,
size_t* wordCount,
uint64_t* words);
/**
* @brief This API retrieves the external data pointer that was previously passed to OH_JSVM_CreateExternal().
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript external value.
* @param result: Pointer to the data wrapped by the JavaScript external value.
* @return Returns JSVM_OK if the API succeeded. If a non-external JSVM_Value is passed in it returns JSVM_INVALID_ARG.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueExternal(JSVM_Env env,
JSVM_Value value,
void** result);
/**
* @brief This API returns the C int32 primitive equivalent of the given JavaScript number.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript number.
* @param result: C int32 primitive equivalent of the given JavaScript number.
* @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt32(JSVM_Env env,
JSVM_Value value,
int32_t* result);
/**
* @brief This API returns the C int64 primitive equivalent of the given JavaScript number.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript number.
* @param result: C int64 primitive equivalent of the given JavaScript number.
* @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt64(JSVM_Env env,
JSVM_Value value,
int64_t* result);
/**
* @brief This API returns the ISO-8859-1-encoded string corresponding the value passed in.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript string.
* @param buf: Buffer to write the ISO-8859-1-encoded string into. If NULL is passed in, the
* length of the string in bytes and excluding the null terminator is returned in result.
* @param bufsize: Size of the destination buffer. When this value is insufficient, the returned string
* is truncated and null-terminated.
* @param result: Number of bytes copied into the buffer, excluding the null terminator.
* @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringLatin1(JSVM_Env env,
JSVM_Value value,
char* buf,
size_t bufsize,
size_t* result);
/**
* @brief This API returns the UTF8-encoded string corresponding the value passed in.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript string.
* @param buf: Buffer to write the UTF8-encoded string into. If NULL is passed in, the length
* of the string in bytes and excluding the null terminator is returned in result.
* @param bufsize: Size of the destination buffer. When this value is insufficient, the returned
* string is truncated and null-terminated.
* @param result: Number of bytes copied into the buffer, excluding the null terminator.
* @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf8(JSVM_Env env,
JSVM_Value value,
char* buf,
size_t bufsize,
size_t* result);
/**
* @brief This API returns the UTF16-encoded string corresponding the value passed in.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript string.
* @param buf: Buffer to write the UTF16-LE-encoded string into. If NULL is passed in,
* the length of the string in 2-byte code units and excluding the null terminator is returned.
* @param bufsize: Size of the destination buffer. When this value is insufficient,
* the returned string is truncated and null-terminated.
* @param result: Number of 2-byte code units copied into the buffer, excluding the null terminator.
* @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf16(JSVM_Env env,
JSVM_Value value,
char16_t* buf,
size_t bufsize,
size_t* result);
/**
* @brief This API returns the C primitive equivalent of the given JSVM_Value as a uint32_t.
*
* @param env: The environment that the API is invoked under.
* @param value: JSVM_Value representing JavaScript number.
* @param result: C primitive equivalent of the given JSVM_Value as a uint32_t.
* @return Returns JSVM_OK if the API succeeded.
* If a non-number JSVM_Value is passed in it returns JSVM_NUMBER_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetValueUint32(JSVM_Env env,
JSVM_Value value,
uint32_t* result);
/**
* @brief This API is used to return the JavaScript singleton object that is used to represent the given boolean value.
*
* @param env: The environment that the API is invoked under.
* @param value: The value of the boolean to retrieve.
* @param result: JSVM_Value representing JavaScript Boolean singleton to retrieve.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetBoolean(JSVM_Env env,
bool value,
JSVM_Value* result);
/**
* @brief This API returns the global object.
*
* @param env: The environment that the API is invoked under.
* @param result: JSVM_Value representing JavaScript global object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetGlobal(JSVM_Env env,
JSVM_Value* result);
/**
* @brief This API returns the null object.
*
* @param env: The environment that the API is invoked under.
* @param result: JSVM_Value representing JavaScript null object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetNull(JSVM_Env env,
JSVM_Value* result);
/**
* @brief This API returns the Undefined object.
*
* @param env: The environment that the API is invoked under.
* @param result: JSVM_Value representing JavaScript Undefined value.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetUndefined(JSVM_Env env,
JSVM_Value* result);
/**
* @brief This API implements the abstract operation ToBoolean()
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to coerce.
* @param result: JSVM_Value representing the coerced JavaScript Boolean.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToBool(JSVM_Env env,
JSVM_Value value,
JSVM_Value* result);
/**
* @brief This API implements the abstract operation ToNumber() as defined. This
* function potentially runs JS code if the passed-in value is an object.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to coerce.
* @param result: JSVM_Value representing the coerced JavaScript number.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToNumber(JSVM_Env env,
JSVM_Value value,
JSVM_Value* result);
/**
* @brief This API implements the abstract operation ToObject().
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to coerce.
* @param result: JSVM_Value representing the coerced JavaScript Object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToObject(JSVM_Env env,
JSVM_Value value,
JSVM_Value* result);
/**
* @brief This API implements the abstract operation ToString().This
* function potentially runs JS code if the passed-in value is an object.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to coerce.
* @param result: JSVM_Value representing the coerced JavaScript string.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToString(JSVM_Env env,
JSVM_Value value,
JSVM_Value* result);
/**
* @brief This API represents behavior similar to invoking the typeof Operator
* on the object as defined. However, there are some differences:It has support
* for detecting an External value.It detects null as a separate type, while
* ECMAScript typeof would detect object.If value has a type that is invalid,
* an error is returned.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value whose type to query.
* @param result: The type of the JavaScript value.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_Typeof(JSVM_Env env,
JSVM_Value value,
JSVM_ValueType* result);
/**
* @brief This API represents invoking the instanceof Operator on the object.
*
* @param env: The environment that the API is invoked under.
* @param object: The JavaScript value to check.
* @param constructor: The JavaScript function object of the constructor function
* to check against.
* @param result: Boolean that is set to true if object instanceof constructor is true.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_Instanceof(JSVM_Env env,
JSVM_Value object,
JSVM_Value constructor,
bool* result);
/**
* @brief This API represents invoking the IsArray operation on the object
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to check.
* @param result: Whether the given object is an array.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsArray(JSVM_Env env,
JSVM_Value value,
bool* result);
/**
* @brief This API checks if the Object passed in is an array buffer.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to check.
* @param result: Whether the given object is an ArrayBuffer.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsArraybuffer(JSVM_Env env,
JSVM_Value value,
bool* result);
/**
* @brief This API checks if the Object passed in is a date.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to check.
* @param result: Whether the given JSVM_Value represents a JavaScript Date object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsDate(JSVM_Env env,
JSVM_Value value,
bool* isDate);
/**
* @brief This API checks if the Object passed in is a typed array.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to check.
* @param result: Whether the given JSVM_Value represents a TypedArray.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsTypedarray(JSVM_Env env,
JSVM_Value value,
bool* result);
/**
* @brief This API checks if the Object passed in is a DataView.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript value to check.
* @param result: Whether the given JSVM_Value represents a DataView.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsDataview(JSVM_Env env,
JSVM_Value value,
bool* result);
/**
* @brief This API represents the invocation of the Strict Equality algorithm.
*
* @param env: The environment that the API is invoked under.
* @param lhs: The JavaScript value to check.
* @param rhs: The JavaScript value to check against.
* @param result: Whether the two JSVM_Value objects are equal.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_StrictEquals(JSVM_Env env,
JSVM_Value lhs,
JSVM_Value rhs,
bool* result);
/**
* @brief This API represents the invocation of the ArrayBuffer detach operation.
*
* @param env: The environment that the API is invoked under.
* @param arraybuffer: The JavaScript ArrayBuffer to be detached.
* @return Returns JSVM_OK if the API succeeded.If a non-detachable ArrayBuffer
* is passed in it returns JSVM_DETACHABLE_ARRAYBUFFER_EXPECTED.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_DetachArraybuffer(JSVM_Env env,
JSVM_Value arraybuffer);
/**
* @brief This API represents the invocation of the ArrayBuffer IsDetachedBuffer operation.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript ArrayBuffer to be checked.
* @param result: Whether the arraybuffer is detached.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsDetachedArraybuffer(JSVM_Env env,
JSVM_Value value,
bool* result);
/**
* @brief This API returns the names of the enumerable properties of object as an array of
* strings. The properties of object whose key is a symbol will not be included.
*
* @param env: The environment that the API is invoked under.
* @param object: The object from which to retrieve the properties.
* @param result: A JSVM_Value representing an array of JavaScript values that represent
* the property names of the object. The API can be used to iterate over result using
* OH_JSVM_GetArrayLength and OH_JSVM_GetElement.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetPropertyNames(JSVM_Env env,
JSVM_Value object,
JSVM_Value* result);
/**
* @brief This API returns an array containing the names of the available properties
* of this object.
*
* @param env: The environment that the API is invoked under.
* @param object: The object from which to retrieve the properties.
* @param keyMode: Whether to retrieve prototype properties as well.
* @param keyFilter: Which properties to retrieve (enumerable/readable/writable).
* @param keyConversion: Whether to convert numbered property keys to strings.
* @param result: result: A JSVM_Value representing an array of JavaScript values
* that represent the property names of the object. OH_JSVM_GetArrayLength and
* OH_JSVM_GetElement can be used to iterate over result.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetAllPropertyNames(JSVM_Env env,
JSVM_Value object,
JSVM_KeyCollectionMode keyMode,
JSVM_KeyFilter keyFilter,
JSVM_KeyConversion keyConversion,
JSVM_Value* result);
/**
* @brief This API set a property on the Object passed in.
*
* @param env: The environment that the API is invoked under.
* @param object: The object on which to set the property.
* @param key: The name of the property to set.
* @param value: The property value.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_SetProperty(JSVM_Env env,
JSVM_Value object,
JSVM_Value key,
JSVM_Value value);
/**
* @brief This API gets the requested property from the Object passed in.
*
* @param env: The environment that the API is invoked under.
* @param object: The object from which to retrieve the property.
* @param key: The name of the property to retrieve.
* @param result: The value of the property.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetProperty(JSVM_Env env,
JSVM_Value object,
JSVM_Value key,
JSVM_Value* result);
/**
* @brief This API checks if the Object passed in has the named property.
*
* @param env: The environment that the API is invoked under.
* @param object: The object to query.
* @param key: The name of the property whose existence to check.
* @param result: Whether the property exists on the object or not.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_HasProperty(JSVM_Env env,
JSVM_Value object,
JSVM_Value key,
bool* result);
/**
* @brief This API attempts to delete the key own property from object.
*
* @param env: The environment that the API is invoked under.
* @param object: The object to query.
* @param key: The name of the property to delete.
* @param result: Whether the property deletion succeeded or not. result
* can optionally be ignored by passing NULL.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_DeleteProperty(JSVM_Env env,
JSVM_Value object,
JSVM_Value key,
bool* result);
/**
* @brief This API checks if the Object passed in has the named own property.
* key must be a string or a symbol, or an error will be thrown. JSVM-API will
* not perform any conversion between data types.
*
* @param env: The environment that the API is invoked under.
* @param object: The object to query.
* @param key: The name of the own property whose existence to check.
* @param result: Whether the own property exists on the object or not.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_HasOwnProperty(JSVM_Env env,
JSVM_Value object,
JSVM_Value key,
bool* result);
/**
* @brief This method is equivalent to calling OH_JSVM_SetProperty with
* a JSVM_Value created from the string passed in as utf8Name.
*
* @param env: The environment that the API is invoked under.
* @param object: The object on which to set the property.
* @param utf8Name: The name of the property to set.
* @param value: The property value.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_SetNamedProperty(JSVM_Env env,
JSVM_Value object,
const char* utf8name,
JSVM_Value value);
/**
* @brief This method is equivalent to calling OH_JSVM_SetProperty with
* a JSVM_Value created from the string passed in as utf8Name.
*
* @param env: The environment that the API is invoked under.
* @param object: The object from which to retrieve the property.
* @param utf8Name: The name of the property to get.
* @param result: The value of the property.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetNamedProperty(JSVM_Env env,
JSVM_Value object,
const char* utf8name,
JSVM_Value* result);
/**
* @brief This method is equivalent to calling OH_JSVM_SetProperty with
* a JSVM_Value created from the string passed in as utf8Name.
*
* @param env: The environment that the API is invoked under.
* @param object: The object to query.
* @param utf8Name: The name of the property whose existence to check.
* @param result: Whether the property exists on the object or not.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_HasNamedProperty(JSVM_Env env,
JSVM_Value object,
const char* utf8name,
bool* result);
/**
* @brief This API sets an element on the Object passed in.
*
* @param env: The environment that the API is invoked under.
* @param object: The object from which to set the properties.
* @param index: The index of the property to set.
* @param value: The property value.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_SetElement(JSVM_Env env,
JSVM_Value object,
uint32_t index,
JSVM_Value value);
/**
* @brief This API gets the element at the requested index.
*
* @param env: The environment that the API is invoked under.
* @param object: The object from which to retrieve the property.
* @param index: The index of the property to get.
* @param result: The value of the property.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetElement(JSVM_Env env,
JSVM_Value object,
uint32_t index,
JSVM_Value* result);
/**
* @brief This API returns if the Object passed in has an element
* at the requested index.
*
* @param env: The environment that the API is invoked under.
* @param object: The object to query.
* @param index: The index of the property whose existence to check.
* @param result: Whether the property exists on the object or not.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_HasElement(JSVM_Env env,
JSVM_Value object,
uint32_t index,
bool* result);
/**
* @brief This API attempts to delete the specified index from object.
*
* @param env: The environment that the API is invoked under.
* @param object: The object to query.
* @param index: The index of the property to delete.
* @param result: Whether the element deletion succeeded or not. result
* can optionally be ignored by passing NULL.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_DeleteElement(JSVM_Env env,
JSVM_Value object,
uint32_t index,
bool* result);
/**
* @brief This method allows the efficient definition of multiple properties
* on a given object. The properties are defined using property descriptors.
* Given an array of such property descriptors, this API will set the properties
* on the object one at a time, as defined by DefineOwnProperty().
*
* @param env: The environment that the API is invoked under.
* @param object: The object from which to retrieve the properties.
* @param propertyCount: The number of elements in the properties array.
* @param properties: The array of property descriptors.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_DefineProperties(JSVM_Env env,
JSVM_Value object,
size_t propertyCount,
const JSVM_PropertyDescriptor* properties);
/**
* @brief This method freezes a given object. This prevents new properties
* from being added to it, existing properties from being removed, prevents
* changing the enumerability, configurability, or writability of existing
* properties, and prevents the values of existing properties from being changed.
* It also prevents the object's prototype from being changed.
*
* @param env: The environment that the API is invoked under.
* @param object: The object to freeze.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ObjectFreeze(JSVM_Env env,
JSVM_Value object);
/**
* @brief This method seals a given object. This prevents new properties
* from being added to it, as well as marking all existing properties as non-configurable.
*
* @param env: The environment that the API is invoked under.
* @param object: The object to seal.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ObjectSeal(JSVM_Env env,
JSVM_Value object);
/**
* @brief This method allows a JavaScript function object to be called from
* a native add-on. This is the primary mechanism of calling back from the
* add-on's native code into JavaScript.
*
* @param env: The environment that the API is invoked under.
* @param recv: The this value passed to the called function.
* @param func: JSVM_Value representing the JavaScript function to be invoked.
* @param argc: The count of elements in the argv array.
* @param argv: Array of JSVM_values representing JavaScript values passed in as arguments to the function.
* @param result: JSVM_Value representing the JavaScript object returned.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CallFunction(JSVM_Env env,
JSVM_Value recv,
JSVM_Value func,
size_t argc,
const JSVM_Value* argv,
JSVM_Value* result);
/**
* @brief This API allows an add-on author to create a function object in native
* code. This is the primary mechanism to allow calling into the add-on's native
* code from JavaScript.The newly created function is not automatically visible
* from script after this call. Instead, a property must be explicitly set on any
* object that is visible to JavaScript, in order for the function to be accessible
* from script.
*
* @param env: The environment that the API is invoked under.
* @param utf8Name: Optional name of the function encoded as UTF8. This is visible
* within JavaScript as the new function object's name property.
* @param length: The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it
* is null-terminated.
* @param cb: The native function which should be called when this function
* object is invoked and data. JSVM_Callback provides more details.
* @param result: JSVM_Value representing the JavaScript function object for the newly
* created function.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateFunction(JSVM_Env env,
const char* utf8name,
size_t length,
JSVM_Callback cb,
JSVM_Value* result);
/**
* @brief This method is used within a callback function to retrieve details about
* the call like the arguments and the this pointer from a given callback info.
*
* @param env: The environment that the API is invoked under.
* @param cbinfo: The callback info passed into the callback function.
* @param argc: Specifies the length of the provided argv array and receives the
* actual count of arguments. argc can optionally be ignored by passing NULL.
* @param argv: C array of JSVM_values to which the arguments will be copied. If
* there are more arguments than the provided count, only the requested number of
* arguments are copied. If there are fewer arguments provided than claimed, the
* rest of argv is filled with JSVM_Value values that represent undefined. argv
* can optionally be ignored by passing NULL.
* @param thisArg: Receives the JavaScript this argument for the call. thisArg
* can optionally be ignored by passing NULL.
* @param data: Receives the data pointer for the callback. data can optionally
* be ignored by passing NULL.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetCbInfo(JSVM_Env env,
JSVM_CallbackInfo cbinfo,
size_t* argc,
JSVM_Value* argv,
JSVM_Value* thisArg,
void** data);
/**
* @brief This API returns the new.target of the constructor call. If the
* current callback is not a constructor call, the result is NULL.
*
* @param env: The environment that the API is invoked under.
* @param cbinfo: The callback info passed into the callback function.
* @param result: The new.target of the constructor call.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetNewTarget(JSVM_Env env,
JSVM_CallbackInfo cbinfo,
JSVM_Value* result);
/**
* @brief his method is used to instantiate a new JavaScript value using
* a given JSVM_Value that represents the constructor for the object.
*
* @param env: The environment that the API is invoked under.
* @param constructor: JSVM_Value representing the JavaScript function to be invoked as a constructor.
* @param argc: The count of elements in the argv array.
* @param argv: Array of JavaScript values as JSVM_Value representing the arguments to
* the constructor. If argc is zero this parameter may be omitted by passing in NULL.
* @param result: JSVM_Value representing the JavaScript object returned, which
* in this case is the constructed object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_NewInstance(JSVM_Env env,
JSVM_Value constructor,
size_t argc,
const JSVM_Value* argv,
JSVM_Value* result);
/**
* @brief When wrapping a C++ class, the C++ constructor callback passed via constructor
* should be a static method on the class that calls the actual class constructor, then
* wraps the new C++ instance in a JavaScript object, and returns the wrapper object.
*
* @param env: The environment that the API is invoked under.
* @param utf8name: Name of the JavaScript constructor function. For clarity, it is
* recommended to use the C++ class name when wrapping a C++ class.
* @param length: The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it
* is null-terminated.
* @param constructor: Struct include callback function that handles constructing instances of the class.
* When wrapping a C++ class, this method must be a static member with the JSVM_Callback.callback
* signature. A C++ class constructor cannot be used.
* Include Optional data to be passed to the constructor callback as the data
* property of the callback info. JSVM_Callback provides more details.
* @param propertyCount: Number of items in the properties array argument.
* @param properties: Array of property descriptors describing static and instance data
* properties, accessors, and methods on the class See JSVM_PropertyDescriptor.
* @param result: A JSVM_Value representing the constructor function for the class.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_DefineClass(JSVM_Env env,
const char* utf8name,
size_t length,
JSVM_Callback constructor,
size_t propertyCount,
const JSVM_PropertyDescriptor* properties,
JSVM_Value* result);
/**
* @brief Wraps a native instance in a JavaScript object. The native instance can
* be retrieved later using OH_JSVM_Unwrap().
*
* @param env: The environment that the API is invoked under.
* @param jsObject: The JavaScript object that will be the wrapper for the native object.
* @param nativeObject: The native instance that will be wrapped in the JavaScript object.
* @param finalizeCb: Optional native callback that can be used to free the native instance
* when the JavaScript object has been garbage-collected.
* @param finalizeHint: Optional contextual hint that is passed to the finalize callback.
* properties, accessors, and methods on the class See JSVM_PropertyDescriptor.
* @param result: Optional reference to the wrapped object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_Wrap(JSVM_Env env,
JSVM_Value jsObject,
void* nativeObject,
JSVM_Finalize finalizeCb,
void* finalizeHint,
JSVM_Ref* result);
/**
* @brief When JavaScript code invokes a method or property accessor on the class, the corresponding
* JSVM_Callback is invoked. If the callback is for an instance method or accessor, then the this
* argument to the callback is the wrapper object; the wrapped C++ instance that is the target of
* the call can be obtained then by calling OH_JSVM_Unwrap() on the wrapper object.
*
* @param env: The environment that the API is invoked under.
* @param jsObject: The object associated with the native instance.
* @param result: Pointer to the wrapped native instance.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_Unwrap(JSVM_Env env,
JSVM_Value jsObject,
void** result);
/**
* @brief Retrieves a native instance that was previously wrapped in the JavaScript object jsObject
* using OH_JSVM_Wrap() and removes the wrapping. If a finalize callback was associated with the wrapping,
* it will no longer be called when the JavaScript object becomes garbage-collected.
*
* @param env: The environment that the API is invoked under.
* @param jsObject: The object associated with the native instance.
* @param result: Pointer to the wrapped native instance.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_RemoveWrap(JSVM_Env env,
JSVM_Value jsObject,
void** result);
/**
* @brief Associates the value of the typeTag pointer with the JavaScript object or external.
* OH_JSVM_CheckObjectTypeTag() can then be used to compare the tag that was attached to the
* object with one owned by the addon to ensure that the object has the right type.
* If the object already has an associated type tag, this API will return JSVM_INVALID_ARG.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript object or external to be marked.
* @param typeTag: The tag with which the object is to be marked.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_TypeTagObject(JSVM_Env env,
JSVM_Value value,
const JSVM_TypeTag* typeTag);
/**
* @brief Compares the pointer given as typeTag with any that can be found on js object.
* If no tag is found on js object or, if a tag is found but it does not match typeTag,
* then result is set to false. If a tag is found and it matches typeTag, then result is set to true.
*
* @param env: The environment that the API is invoked under.
* @param value: The JavaScript object or external whose type tag to examine.
* @param typeTag: The tag with which to compare any tag found on the object.
* @param result: Whether the type tag given matched the type tag on the object. false is also returned
* if no type tag was found on the object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CheckObjectTypeTag(JSVM_Env env,
JSVM_Value value,
const JSVM_TypeTag* typeTag,
bool* result);
/**
* @brief This API can be called multiple times on a single JavaScript object.
*
* @param env: The environment that the API is invoked under.
* @param jsObject: The JavaScript object to which the native data will be attached.
* @param finalizeData: Optional data to be passed to finalizeCb.
* @param finalizeCb: Native callback that will be used to free the native data when the
* JavaScript object has been garbage-collected. JSVM_Finalize provides more details.
* @param finalizeHint: Optional contextual hint that is passed to the finalize callback.
* @param result: Optional reference to the JavaScript object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_AddFinalizer(JSVM_Env env,
JSVM_Value jsObject,
void* finalizeData,
JSVM_Finalize finalizeCb,
void* finalizeHint,
JSVM_Ref* result);
/**
* @brief This API returns the highest JSVM-API version supported by the JSVM runtime.
*
* JSVM-API is planned to be additive such that newer releases of JSVM may support additional
* API functions. In order to allow an addon to use a newer function when running with versions
* of JSVM that support it, while providing fallback behavior when running with JSVM
* versions that don't support it.
* @param env: The environment that the API is invoked under.
* @param result: The highest version of JSVM-API supported.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetVersion(JSVM_Env env,
uint32_t* result);
/**
* @brief Return information of the VM.
*
* @param result: The information of the VM.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_GetVMInfo(JSVM_VMInfo* result);
/**
* @brief This function gives V8 an indication of the amount of externally
* allocated memory that is kept alive by JavaScript objects (i.e. a JavaScript
* object that points to its own memory allocated by a native addon). Registering
* externally allocated memory will trigger global garbage collections more often
* than it would otherwise.
*
* @param env: The environment that the API is invoked under.
* @param changeInBytes: The change in externally allocated memory that is kept
* alive by JavaScript objects.
* @param result: The adjusted value
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_AdjustExternalMemory(JSVM_Env env,
int64_t changeInBytes,
int64_t* result);
/**
* @brief This function notifies the VM that the system is running low on memory
* and optionally triggers a garbage collection.
*
* @param env: The environment that the API is invoked under.
* @param level: The memory pressure level set to the current VM.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_MemoryPressureNotification(JSVM_Env env,
JSVM_MemoryPressureLevel level);
/**
* @brief This API creates a deferred object and a JavaScript promise.
*
* @param env: The environment that the API is invoked under.
* @param deferred: A newly created deferred object which can later be
* passed to OH_JSVM_ResolveDeferred() or OH_JSVM_RejectDeferred() to resolve
* resp. reject the associated promise.
* @param promise: The JavaScript promise associated with the deferred object.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreatePromise(JSVM_Env env,
JSVM_Deferred* deferred,
JSVM_Value* promise);
/**
* @brief This API resolves a JavaScript promise by way of the deferred object with
* which it is associated. Thus, it can only be used to resolve JavaScript promises
* for which the corresponding deferred object is available. This effectively means
* that the promise must have been created using OH_JSVM_CreatePromise() and the deferred
* object returned from that call must have been retained in order to be passed to this API.
*
* @param env: The environment that the API is invoked under.
* @param deferred: The deferred object whose associated promise to resolve.
* @param resolution: The value with which to resolve the promise.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_ResolveDeferred(JSVM_Env env,
JSVM_Deferred deferred,
JSVM_Value resolution);
/**
* @brief This API rejects a JavaScript promise by way of the deferred object with
* which it is associated. Thus, it can only be used to reject JavaScript promises
* for which the corresponding deferred object is available. This effectively means
* that the promise must have been created using OH_JSVM_CreatePromise() and the deferred
* object returned from that call must have been retained in order to be passed to this API.
*
* @param env: The environment that the API is invoked under.
* @param deferred: The deferred object whose associated promise to resolve.
* @param rejection: The value with which to reject the promise.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_RejectDeferred(JSVM_Env env,
JSVM_Deferred deferred,
JSVM_Value rejection);
/**
* @brief This API return indicating whether promise is a native promise object.
* @param env: The environment that the API is invoked under.
* @param value: The value to examine
* @param isPromise: Flag indicating whether promise is a native promise object
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_IsPromise(JSVM_Env env,
JSVM_Value value,
bool* isPromise);
/**
* @brief This API parses a JSON string and returns it as value if successful.
* @param env: The environment that the API is invoked under.
* @param jsonString: The string to parse.
* @param result: The parse value if successful.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_JsonParse(JSVM_Env env,
JSVM_Value jsonString,
JSVM_Value* result);
/**
* @brief This API stringifies the object and returns it as string if successful.
* @param env: The environment that the API is invoked under.
* @param jsonObject: The object to stringify.
* @param result: The string if successfully stringified.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_JsonStringify(JSVM_Env env,
JSVM_Value jsonObject,
JSVM_Value* result);
/**
* @brief This API create the startup snapshot of the VM.
* @param vm: The environment that the API is invoked under.
* @param contextCount: The object to stringify.
* @param contexts: The array of contexts to add to the snapshot.
* @param blobData: The snapshot data.
* @param blobSize: The size of snapshot data.
* @return Returns JSVM_OK if the API succeeded.
* @since 11
*/
JSVM_EXTERN JSVM_Status OH_JSVM_CreateSnapshot(JSVM_VM vm,
size_t contextCount,
const JSVM_Env* contexts,
const char** blobData,
size_t* blobSize);
EXTERN_C_END
/** @} */
#endif /* ARK_RUNTIME_JSVM_JSVM_H */
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。
马建仓 AI 助手