native_interface_arkweb.h

Overview

Declares APIs used to register objects and execute JavaScript code.

File to include: <web/native_interface_arkweb.h>

Library: libohweb.so

System capability: SystemCapability.Web.Webview.Core

Since: 11

Related module: Web

Summary

Structs

Name	typedef Keyword	Description
ArkWeb_BlanklessInfo	ArkWeb_BlanklessInfo	Defines the prediction information about blankless loading, including the first screen similarity, first screen loading duration, and error code. The application determines whether to enable frame insertion for blankless loading based on the prediction information.

Enums

Name	typedef Keyword	Description
ArkWebEngineVersion	ArkWebEngineVersion	For details about the ArkWeb kernel version, see Adaptation Guide for the M114 Kernel on OpenHarmony 6.0.

Functions

Name	typedef Keyword	Description
typedef void (*NativeArkWeb_OnJavaScriptCallback)(const char*)	NativeArkWeb_OnJavaScriptCallback	Called to return the result after the JavaScript code is executed.
typedef char* (*NativeArkWeb_OnJavaScriptProxyCallback)(const char** argv, int32_t argc)	NativeArkWeb_OnJavaScriptProxyCallback	Called when a JavaScript proxy is registered.
typedef void (*NativeArkWeb_OnValidCallback)(const char*)	NativeArkWeb_OnValidCallback	Called when a Web component is valid.
typedef void (*NativeArkWeb_OnDestroyCallback)(const char*)	NativeArkWeb_OnDestroyCallback	Called when a Web component is destroyed.
typedef void (*OH_ArkWeb_OnCookieSaveCallback)(ArkWeb_ErrorCode errorCode)	OH_ArkWeb_OnCookieSaveCallback	Called when a cookie is saved. Since: 20
void OH_NativeArkWeb_RunJavaScript(const char* webTag, const char* jsCode, NativeArkWeb_OnJavaScriptCallback callback)	-	Loads and asynchronously executes a JavaScript code in the current page.
void OH_NativeArkWeb_RegisterJavaScriptProxy(const char* webTag, const char* objName, const char** methodList,NativeArkWeb_OnJavaScriptProxyCallback* callback, int32_t size, bool needRefresh)	-	Displays the list of registered objects and function names.
void OH_NativeArkWeb_UnregisterJavaScriptProxy(const char* webTag, const char* objName)	-	Deletes a registered object and its callback.
void OH_NativeArkWeb_SetJavaScriptProxyValidCallback(const char* webTag, NativeArkWeb_OnValidCallback callback)	-	Sets a callback used when an object is valid.
NativeArkWeb_OnValidCallback OH_NativeArkWeb_GetJavaScriptProxyValidCallback(const char* webTag)	-	Obtains the callback used when a registered object is valid.
void OH_NativeArkWeb_SetDestroyCallback(const char* webTag, NativeArkWeb_OnDestroyCallback callback)	-	Sets a callback used when a component is destroyed.
NativeArkWeb_OnDestroyCallback OH_NativeArkWeb_GetDestroyCallback(const char* webTag)	-	Obtains the callback used when a registered component is destroyed.
ArkWeb_ErrorCode OH_NativeArkWeb_LoadData(const char* webTag,const char* data,const char* mimeType,const char* encoding,const char* baseUrl,const char* historyUrl)	-	Loads data or URLs. This function must be called in the main thread.
void OH_NativeArkWeb_RegisterAsyncThreadJavaScriptProxy(const char* webTag,const ArkWeb_ProxyObjectWithResult* proxyObject, const char* permission)	-	Registers a JavaScript object that contains callback methods, which can have return values. This object will be registered into all frames of the current page, including all iframes, and can be accessed by using the name specified in ArkWeb_ProxyObjectWithResult. The object takes effect in JavaScript only after the page is loaded or reloaded next time. Its methods are executed in the worker thread of ArkWeb.
ArkWeb_ErrorCode OH_ArkWebCookieManager_SaveCookieSync()	-	Saves all cookies that can be accessed through the CookieManager API to disks. To use this API in a non-UI thread, you need to use OH_ArkWeb_GetNativeAPI to initialize the CookieManager API. Since: 20
void OH_ArkWebCookieManager_SaveCookieAsync(OH_ArkWeb_OnCookieSaveCallback callback)	-	Saves all cookies that can be accessed through the CookieManager API to disks. If the CookieManager API is not initialized, this API is automatically executed on the UI thread. Since: 20
ArkWeb_BlanklessInfo OH_NativeArkWeb_GetBlanklessInfoWithKey(const char* webTag, const char* key)	-	Obtains the first screen loading prediction information, and starts to generate the loading transition frame. The application determines whether to enable blankless loading based on the information. For details, see ArkWeb_BlanklessInfo. This API must be used together with the OH_NativeArkWeb_SetBlanklessLoadingWithKey API and must be called before the page loading API is triggered and after WebViewController is bound to the Web component.
ArkWeb_BlanklessErrorCode OH_NativeArkWeb_SetBlanklessLoadingWithKey(const char* webTag, const char* key, bool isStarted)	-	Sets whether to enable blankless loading. This API must be used together with the OH_NativeArkWeb_GetBlanklessInfoWithKey API.
void OH_NativeArkWeb_ClearBlanklessLoadingCache(const char* key[], uint32_t size)	-	Clears the blankless loading cache of the page with a specified key value.
uint32_t OH_NativeArkWeb_SetBlanklessLoadingCacheCapacity(uint32_t capacity)	-	Sets the persistent cache capacity of the blankless loading solution and returns the value that takes effect. The default cache capacity is 30 MB, and the maximum cache capacity is 100 MB. When this limit is exceeded, transition frames that are not frequently used are eliminated.
void OH_NativeArkWeb_SetActiveWebEngineVersion(ArkWebEngineVersion webEngineVersion)	-	Sets the ArkWeb kernel version. If the system does not support the specified version, the setting is invalid. This API is a global static method and must be called before initializeWebEngine is called. If any Web component has been loaded, the setting of this API is invalid.
ArkWebEngineVersion OH_NativeArkWeb_GetActiveWebEngineVersion()	-	Obtain the current ArkWeb kernel version.
bool OH_NativeArkWeb_IsActiveWebEngineEvergreen()	-	Checks whether the ArkWeb kernel used by the application is the evergreen kernel, that is, the latest kernel of the system.
void OH_NativeArkWeb_LazyInitializeWebEngineInCookieManager(bool lazy)	-	Sets whether to delay the initialization of the ArkWeb kernel. If this method is not called, the ArkWeb kernel is not delayed by default.

Enum Description

ArkWebEngineVersion

enum ArkWebEngineVersion

Description

For details about the ArkWeb kernel version, see Adaptation Guide for the M114 Kernel on OpenHarmony 6.0.

Kernel Type	Name	Description
Evergreen kernel	EVERGREEN WebCore	Latest Web kernel of the system, based on which the complete functionalities are implemented. This kernel is recommended for applications.
Legacy kernel	LEGACY WebCore	A previous-release kernel that receives only security and PR-related fixes, used solely for compatibility rollback, and is supported for a fixed duration only.

Since: 20

Enum	Description
SYSTEM_DEFAULT = 0	Default system kernel. For OpenHarmony 6.0, the default kernel is M132.
ARKWEB_M114 = 1	Legacy kernel of OpenHarmony 6.0. You can select this legacy kernel. If it does not exist, the setting is invalid.
ARKWEB_M132 = 2	Evergreen kernel of OpenHarmony 6.0, which is M132 by default. If it does not exist, the setting is invalid.
ARKWEB_EVERGREEN = 99999	Evergreen kernel, which is the latest kernel of the system. You can choose to use the latest kernel for each system version. This setting takes effect for OpenHarmony 6.1 and later versions. Since: 23

Function Description

NativeArkWeb_OnJavaScriptCallback()

typedef void (*NativeArkWeb_OnJavaScriptCallback)(const char*)

Description

Called to return the result after the JavaScript code is executed.

Since: 11

NativeArkWeb_OnJavaScriptProxyCallback()

typedef char* (*NativeArkWeb_OnJavaScriptProxyCallback)(const char** argv, int32_t argc)

Description

Called when a JavaScript proxy is registered.

Since: 11

NativeArkWeb_OnValidCallback()

typedef void (*NativeArkWeb_OnValidCallback)(const char*)

Description

Called when a Web component is valid.

Since: 11

NativeArkWeb_OnDestroyCallback()

typedef void (*NativeArkWeb_OnDestroyCallback)(const char*)

Description

Called when a Web component is destroyed.

Since: 11

OH_ArkWeb_OnCookieSaveCallback()

typedef void (*OH_ArkWeb_OnCookieSaveCallback)(ArkWeb_ErrorCode errorCode)

Description

Called when a cookie is saved.

Since: 20

Parameters

Name	Description
ArkWeb_ErrorCode errorCode	ARKWEB_SUCCESS: The cookie is successfully saved. ARKWEB_COOKIE_SAVE_FAILED: Failed to save the cookie. ARKWEB_COOKIE_MANAGER_INITIALIZE_FAILED: The CookieManager initialization failed.

OH_NativeArkWeb_RunJavaScript()

void OH_NativeArkWeb_RunJavaScript(const char* webTag, const char* jsCode, NativeArkWeb_OnJavaScriptCallback callback)

Description

Loads and asynchronously executes a JavaScript code in the current page.

System capability: SystemCapability.Web.Webview.Core

Since: 11

Parameters

Name	Description
const char* webTag	Name of the Web component.
const char* jsCode	A piece of JavaScript code script.
NativeArkWeb_OnJavaScriptCallback callback	Callback for notifying the code execution result.

OH_NativeArkWeb_RegisterJavaScriptProxy()

void OH_NativeArkWeb_RegisterJavaScriptProxy(const char* webTag, const char* objName, const char** methodList,NativeArkWeb_OnJavaScriptProxyCallback* callback, int32_t size, bool needRefresh)

Description

Displays the list of registered objects and function names.

System capability: SystemCapability.Web.Webview.Core

Since: 11

Parameters

Name	Description
const char* webTag	Name of the Web component.
const char* objName	Name of the registered object.
const char** methodList	Name of the registered method list.
NativeArkWeb_OnJavaScriptProxyCallback* callback	Registered callback.
int32_t size	Number of registered callbacks.
bool needRefresh	Whether a page need to be refreshed. The value true indicates that the page needs to be refreshed, and false indicates the opposite.

OH_NativeArkWeb_UnregisterJavaScriptProxy()

void OH_NativeArkWeb_UnregisterJavaScriptProxy(const char* webTag, const char* objName)

Description

Deletes a registered object and its callback.

System capability: SystemCapability.Web.Webview.Core

Since: 11

Parameters

Name	Description
const char* webTag	Name of the Web component.
const char* objName	Name of the registered object.

OH_NativeArkWeb_SetJavaScriptProxyValidCallback()

void OH_NativeArkWeb_SetJavaScriptProxyValidCallback(const char* webTag, NativeArkWeb_OnValidCallback callback)

Description

Sets a callback used when an object is valid.

System capability: SystemCapability.Web.Webview.Core

Since: 11

Parameters

Name	Description
const char* webTag	Name of the Web component.
NativeArkWeb_OnValidCallback callback	Callback used when an object is valid.

OH_NativeArkWeb_GetJavaScriptProxyValidCallback()

NativeArkWeb_OnValidCallback OH_NativeArkWeb_GetJavaScriptProxyValidCallback(const char* webTag)

Description

Obtains the callback used when a registered object is valid.

System capability: SystemCapability.Web.Webview.Core

Since: 11

Parameters

Name	Description
const char* webTag	Name of the Web component.

Returns

Type	Description
NativeArkWeb_OnValidCallback	Callback used when a registered object is valid. If no valid callback function is set for the webTag parameter, a null pointer is returned.

OH_NativeArkWeb_SetDestroyCallback()

void OH_NativeArkWeb_SetDestroyCallback(const char* webTag, NativeArkWeb_OnDestroyCallback callback)

Description

Sets a callback used when a component is destroyed.

System capability: SystemCapability.Web.Webview.Core

Since: 11

Parameters

Name	Description
const char* webTag	Name of the Web component.
NativeArkWeb_OnDestroyCallback callback	Callback used when a component is destroyed.

OH_NativeArkWeb_GetDestroyCallback()

NativeArkWeb_OnDestroyCallback OH_NativeArkWeb_GetDestroyCallback(const char* webTag)

Description

Obtains the callback used when a registered component is destroyed.

System capability: SystemCapability.Web.Webview.Core

Since: 11

Parameters

Name	Description
const char* webTag	Name of the Web component.

Returns

Type	Description
NativeArkWeb_OnDestroyCallback	Callback used when a registered component is destroyed. If no destroy callback function is set for the webTag parameter, a null pointer is returned.

OH_NativeArkWeb_LoadData()

ArkWeb_ErrorCode OH_NativeArkWeb_LoadData(const char* webTag,const char* data,const char* mimeType,const char* encoding,const char* baseUrl,const char* historyUrl)

Description

Loads data or URLs. This function must be called in the main thread.

System capability: SystemCapability.Web.Webview.Core

Since: 15

Parameters

Name	Description
const char* webTag	Name of the Web component.
const char* data	String being base64 or URL encoded, which cannot be empty.
const char* mimeType	Media type, such as text/html, which cannot be empty.
const char* encoding	Encoding type, such as UTF-8, which cannot be empty.
const char* baseUrl	URL (HTTP/HTTPS/Data), which is assigned by the Web component to window.origin.
const char* historyUrl	Historical URL. If this parameter is not empty, it can be managed in historical records to implement backward and forward navigation.

Returns

Type

Description

ArkWeb_ErrorCode

Error codes of LoadData. ARKWEB_SUCCESS: The data is successfully loaded. ARKWEB_INVALID_PARAM: The mandatory parameter is not specified, the parameter type is incorrect, or the parameter verification fails. ARKWEB_INIT_ERROR: The initialization failed because no valid Web component is found based on the input webTag. ARKWEB_LIBRARY_OPEN_FAILURE: Failed to open the dynamic link library. ARKWEB_LIBRARY_SYMBOL_NOT_FOUND: The required symbol is not found in the dynamic link library.

OH_NativeArkWeb_RegisterAsyncThreadJavaScriptProxy()

void OH_NativeArkWeb_RegisterAsyncThreadJavaScriptProxy(const char* webTag,const ArkWeb_ProxyObjectWithResult* proxyObject, const char* permission)

Description

Registers a JavaScript object that contains callback methods, which can have return values. This object will be registered into all frames of the current page, including all iframes, and can be accessed by using the name specified in ArkWeb_ProxyObjectWithResult. The object takes effect in JavaScript only after the page is loaded or reloaded next time. Its methods are executed in the worker thread of ArkWeb.

Since: 20

Parameters

Name	Description
const char* webTag	Name of the Web component.
const ArkWeb_ProxyObjectWithResult* proxyObject	Object to be registered.
const char* permission	A JSON string used to configure the object and method levels of the JSBridge permission. This value is empty by default.

OH_ArkWebCookieManager_SaveCookieSync()

ArkWeb_ErrorCode OH_ArkWebCookieManager_SaveCookieSync()

Description

Saves all cookies that can be accessed through the CookieManager API to disks. To use this API in a non-UI thread, you need to use OH_ArkWeb_GetNativeAPI to initialize the CookieManager API.

Since: 20

Returns

Type

Description

ArkWeb_ErrorCode

Error codes of SaveCookieSync. ARKWEB_SUCCESS: The cookie is successfully saved. ARKWEB_COOKIE_SAVE_FAILED: Failed to save the cookie. ARKWEB_COOKIE_MANAGER_INITIALIZE_FAILED: The CookieManager initialization failed. ARKWEB_COOKIE_MANAGER_NOT_INITIALIZED: This API cannot be invoked in a non-UI thread without initializing the CookieManager API. You need to use OH_ArkWeb_GetNativeAPI to initialize the CookieManager API first.

OH_ArkWebCookieManager_SaveCookieAsync()

void OH_ArkWebCookieManager_SaveCookieAsync(OH_ArkWeb_OnCookieSaveCallback callback)

Description

Saves all cookies that can be accessed through the CookieManager API to disks. If the CookieManager API is not initialized, this API is automatically executed on the UI thread.

Since: 20

Parameters

Name	Description
OH_ArkWeb_OnCookieSaveCallback* callback	Callback triggered when cookies are saved.

OH_NativeArkWeb_GetBlanklessInfoWithKey()

ArkWeb_BlanklessInfo OH_NativeArkWeb_GetBlanklessInfoWithKey(const char* webTag, const char* key)

Description

Obtains the first screen loading prediction information, and starts to generate the loading transition frame. The application determines whether to enable blankless loading based on the information. For details, see ArkWeb_BlanklessInfo. This API must be used together with the OH_NativeArkWeb_SetBlanklessLoadingWithKey API and must be called before the page loading API is triggered and after WebViewController is bound to the Web component.

NOTE

• The default size of the persistent cache capacity is 30 MB (about 30 pages). You can set the cache capacity by calling OH_NativeArkWeb_SetBlanklessLoadingCacheCapacity. For details, see the description of this API. When the maximum capacity is exceeded, the cache is updated based on the Least Recently Used (LRU) mechanism. The persistent cache data that has been stored for more than seven days is automatically cleared. After the cache is cleared, the optimization effect appears when the page is loaded for the third time.
• If the value of similarity in ArkWeb_BlanklessInfo is extremely low, check whether the key value is correctly passed.
• After this API is called, page loading snapshot detection and transition frame generation calculation are enabled, which generates certain resource overhead.
• Blankless loading consumes resources, which depends on the resolution of the Web component. It is assumed that a width and a height of the resolution are respectively w and h. When a page is opened, the peak memory usage increases by about 12×w×h B. After the page is opened, the memory is reclaimed, which does not affect the stable memory usage. When the size of the solid-state application cache is increased, the increased cache of each page is about w×h/10 B and the cache is located in the application cache.

Required permissions: ohos.permission.INTERNET and ohos.permission.GET_NETWORK_INFO

Since: 20

Device behavior differences: This API can be called on phones. For other device types, error code 801 is returned.

Parameters

Name	Description
const char* webTag	Name of the Web component.
const char* key	Key value that uniquely identifies the page. The value cannot be empty and can contain a maximum of 2048 characters. Invalid values do not take effect.

Returns

Type	Description
ArkWeb_BlanklessInfo	Prediction information about blankless loading, including the first screen similarity and first screen loading duration. The application determines whether to enable blankless loading based on the prediction information.

OH_NativeArkWeb_SetBlanklessLoadingWithKey()

ArkWeb_BlanklessErrorCode OH_NativeArkWeb_SetBlanklessLoadingWithKey(const char* webTag, const char* key, bool isStarted)

Description

Sets whether to enable blankless loading. This API must be used together with the OH_NativeArkWeb_GetBlanklessInfoWithKey API.

NOTE

• This API must be called after the page loading API is triggered. Other constraints are the same as those of OH_NativeArkWeb_GetBlanklessInfoWithKey.
• The page must be loaded in the component that calls this set of APIs.
• When the similarity is low, the system will deem the scene change too abrupt and frame insertion will fail.

Required permissions: ohos.permission.INTERNET and ohos.permission.GET_NETWORK_INFO

Since: 20

Parameters

Name	Description
const char* webTag	Name of the Web component.
const char* key	Key value that uniquely identifies the page. The value must be the same as the key value of the OH_NativeArkWeb_GetBlanklessInfoWithKey API. The value cannot be empty and can contain a maximum of 2048 characters. When an invalid value is set, the error code ArkWeb_BlanklessErrorCode is returned and the frame insertion does not take effect.
bool isStarted	Whether to enable frame insertion. The value true indicates to enable frame insertion, and false indicates the opposite. The default value is false.

Returns

Type	Description
ArkWeb_BlanklessErrorCode	Whether the API is successfully called. For details, see ArkWeb_BlanklessErrorCode.

OH_NativeArkWeb_ClearBlanklessLoadingCache()

void OH_NativeArkWeb_ClearBlanklessLoadingCache(const char* key[], uint32_t size)

Description

Clears the blankless loading cache of the page with a specified key value.

In an applet or web application, when the content changes significantly during page loading, an obvious scene change may occur. If you are concerned about this change, you can use this API to clear the page cache.

NOTE

• After the page is cleared, the optimization effect appears when the page is loaded for the third time.

Since: 20

Parameters

Name	Description
const char* key[]	Key value list on the pages using the blankless optimization solution. The key value has been specified in OH_NativeArkWeb_GetBlanklessInfoWithKey. Default value: key value list of all pages cached by the blankless optimization solution. The key length cannot exceed 2048 characters, and the number of keys must be less than or equal to 100. The key value is the same as that input to the Web component during page loading. If the key length exceeds 2048 characters, the key does not take effect. If the key length exceeds 100 characters, the first 100 characters are used. If the key length is NULL, the default value is used.
uint32_t size	Size of the key array. The default value is 0. The value ranges from 0 to 100. If the size exceeds 100, the first 100 keys are used. When an invalid value is set, the value 0 is used.

OH_NativeArkWeb_SetBlanklessLoadingCacheCapacity()

uint32_t OH_NativeArkWeb_SetBlanklessLoadingCacheCapacity(uint32_t capacity)

Description

Sets the persistent cache capacity of the blankless loading solution and returns the value that takes effect. The default cache capacity is 30 MB, and the maximum cache capacity is 100 MB. When this limit is exceeded, transition frames that are not frequently used are eliminated.

Since: 20

Parameters

Name	Description
uint32_t capacity	Persistent cache capacity, in MB. The maximum value is 100 MB. The default value is 30 MB. The value ranges from 0 to 100. If this parameter is set to 0, no cache capacity is available and the functionality is disabled globally. When a value less than 0 is set, the value 0 takes effect. When a value greater than 100 is set, the value 100 takes effect.

Returns

Type	Description
uint32_t	The effective value that ranges from 0 MB to 100 MB. When a value less than 0 is set, the value 0 takes effect. When a value greater than 100 is set, the value 100 takes effect.

OH_NativeArkWeb_SetActiveWebEngineVersion()

void OH_NativeArkWeb_SetActiveWebEngineVersion(ArkWebEngineVersion webEngineVersion)

Description

Sets the ArkWeb kernel version. If the system does not support the specified version, the setting is invalid.

This API is a global static method and must be called before initializeWebEngine is called. If any Web component has been loaded, the setting of this API is invalid.

Legacy kernel adaptation

Since OpenHarmony 6.0, some ArkWeb APIs do not take effect when the legacy kernel is used. For details, see Adaptation Guide for the M114 Kernel on OpenHarmony 6.0.

Since: 20

Parameters

Name	Description
ArkWebEngineVersion webEngineVersion	ArkWeb kernel version. For details, see ArkWebEngineVersion.

OH_NativeArkWeb_GetActiveWebEngineVersion()

ArkWebEngineVersion OH_NativeArkWeb_GetActiveWebEngineVersion()

Description

Obtains the current ArkWeb kernel version.

Since: 20

Returns

Type	Description
ArkWebEngineVersion	The current ArkWeb kernel version defined by ArkWebEngineVersion.

OH_NativeArkWeb_IsActiveWebEngineEvergreen()

bool OH_NativeArkWeb_IsActiveWebEngineEvergreen()

Description

Checks whether the ArkWeb kernel used by the application is the evergreen kernel, that is, the latest kernel of the system.

Since: 23

Returns

Type	Description
bool	Whether the kernel used by the application is the evergreen kernel. The value true indicates that the kernel used by the application is the evergreen kernel, and false indicates the opposite.

OH_NativeArkWeb_LazyInitializeWebEngineInCookieManager()

void OH_NativeArkWeb_LazyInitializeWebEngineInCookieManager(bool lazy)

Description

Sets whether to delay the initialization of the ArkWeb kernel. If this method is not called, the ArkWeb kernel is not delayed by default.

NOTE

• This API is a global static method and must be called before the Web component is used and the ArkWeb kernel is initialized. Otherwise, the setting is invalid.
• This API is applicable only to APIs that initialize the CookieManager after being called, for example, the ArkWeb_CookieManagerAPI APIs. When this API is called, the ArkWeb kernel is not initialized during the initialization of CookieManager. You need to initialize the ArkWeb kernel later.

Since: 22

Parameters

Name	Description
bool lazy	Whether to delay the initialization of the ArkWeb kernel. The value true means to delay the initialization, and false means the opposite.