* Copyright (c) 2023 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.
*/
* @addtogroup Web
* @{
*
* @brief Provides APIs to use javascript proxy and run javascript code.
* @since 11
*/
* @file native_interface_arkweb.h
*
* @brief Declares the APIs to use javascript proxy and run javascript code.
* @kit ArkWeb
* @library libohweb.so
* @syscap SystemCapability.Web.Webview.Core
* @since 11
*/
#ifndef NATIVE_INTERFACE_ARKWEB_H
#define NATIVE_INTERFACE_ARKWEB_H
#include <stdbool.h>
#include <stdint.h>
#include "arkweb_error_code.h"
#include "arkweb_type.h"
#ifdef __cplusplus
extern "C" {
#endif
* @brief Defines the javascript callback of the web component.
*
* @since 11
*/
typedef void (*NativeArkWeb_OnJavaScriptCallback)(const char*);
* @brief Defines the javascript proxy callback of the web component.
*
* @since 11
*/
typedef char* (*NativeArkWeb_OnJavaScriptProxyCallback)(const char** argv, int32_t argc);
* @brief Defines the valid callback of the web component.
*
* @since 11
*/
typedef void (*NativeArkWeb_OnValidCallback)(const char*);
* @brief Defines the destroy callback of the web component.
*
* @since 11
*/
typedef void (*NativeArkWeb_OnDestroyCallback)(const char*);
* @brief Defines the callback of save cookie.
* @param errorCode {@link ARKWEB_SUCCESS} Save cookie success.
* {@link ARKWEB_COOKIE_MANAGER_INITIALIZE_FAILED} Cookie manager initialize failed.
* {@link ARKWEB_COOKIE_SAVE_FAILED} Save cookie failed.
* @since 20
*/
typedef void (*OH_ArkWeb_OnCookieSaveCallback)(ArkWeb_ErrorCode errorCode);
* @brief Describes prediction information about blankless loading, including the first screen similarity, first screen
* loading duration, and error codes. The application determines whether to enable the blankless loading solution based
* on the prediction information.
*
* @since 20
*/
typedef struct {
* Error codes of blankless loading. For details, see {@link ArkWeb_BlanklessErrorCode}.
*/
ArkWeb_BlanklessErrorCode errCode;
* First screen similarity, which is calculated based on the historical first screen content. The value ranges from
* 0 to 1.0. 1.0 indicates that the content is the same. A value closer to 1 indicates a higher similarity. This
* value is lagging, and the similarity of the local loading is displayed in the next loading. You are advised not
* to enable the blankless loading frame insertion solution when the similarity is low.
*/
double similarity;
* Loading duration estimated based on the historical first screen loading durations, in milliseconds. The value
* must be greater than 0.
*/
int32_t loadingTime;
} ArkWeb_BlanklessInfo;
* @brief For details about the ArkWeb kernel version, see
* [Adaptation Guide for the M114 Kernel on OpenHarmony 6.0]
* (https://gitcode.com/openharmony-tpc/chromium_src/blob/master/web/ReleaseNote/CompatibleWithLegacyWebEngine_6.0.md),
* [Adaptation Guide for the M114 Kernel on OpenHarmony 7.0]
* (https://gitcode.com/openharmony-tpc/chromium_src/blob/master/web/ReleaseNote/CompatibleWithLegacyWebEngine_7.0.md).
*
* @since 20
*/
typedef enum {
* @brief Default system kernel. For OpenHarmony 6.0, the default kernel is M132.
*
* @since 20
*/
SYSTEM_DEFAULT = 0,
* @brief Legacy kernel of OpenHarmony 6.0. You can select this legacy kernel. If it does not exist, the setting
* is invalid.
*
* @since 20
*/
ARKWEB_M114 = 1,
* @brief Evergreen kernel of OpenHarmony 6.0, which is M132 by default. If it does not exist, the setting is
* invalid.
*
* @since 20
*/
ARKWEB_M132 = 2,
* @brief Evergreen kernel of OpenHarmony 7.0, which is M144 by default. If it does not exist, the setting is
* invalid.
*
* @since 26.0.0
*/
ARKWEB_M144 = 3,
* @brief 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
*/
ARKWEB_EVERGREEN = 99999
} ArkWebEngineVersion;
* @brief Loads a piece of code and execute JS code in the context of the currently displayed page.
*
* @param webTag The name of the web component.
* @param jsCode a piece of javascript code.
* @param callback Callbacks execute JavaScript script results.
*
* @syscap SystemCapability.Web.Webview.Core
* @since 11
*/
void OH_NativeArkWeb_RunJavaScript(const char* webTag, const char* jsCode, NativeArkWeb_OnJavaScriptCallback callback);
* @brief Registers the JavaScript object and method list.
*
* @param webTag The name of the web component.
* @param objName The name of the registered object.
* @param methodList The method of the application side JavaScript object participating in the registration.
* @param callback The callback function registered by developer is called back when HTML side uses.
* @param size The size of the callback.
* @param needRefresh if web need refresh.
*
* @syscap SystemCapability.Web.Webview.Core
* @since 11
*/
void OH_NativeArkWeb_RegisterJavaScriptProxy(const char* webTag, const char* objName, const char** methodList,
NativeArkWeb_OnJavaScriptProxyCallback* callback, int32_t size, bool needRefresh);
* @brief Deletes the registered object which th given name.
*
* @param webTag The name of the web component.
* @param objName The name of the registered object.
*
* @syscap SystemCapability.Web.Webview.Core
* @since 11
*/
void OH_NativeArkWeb_UnregisterJavaScriptProxy(const char* webTag, const char* objName);
* @brief Registers the valid callback.
*
* @param webTag The name of the web component.
* @param callback The callback in which we can register object.
*
* @syscap SystemCapability.Web.Webview.Core
* @since 11
*/
void OH_NativeArkWeb_SetJavaScriptProxyValidCallback(const char* webTag, NativeArkWeb_OnValidCallback callback);
* @brief Get the valid callback.
*
* @param webTag The name of the web component.
* @return Return the valid callback function registered. If the valid callback function
* specified by the parameter webTag is not set, a null pointer is returned.
*
* @syscap SystemCapability.Web.Webview.Core
* @since 11
*/
NativeArkWeb_OnValidCallback OH_NativeArkWeb_GetJavaScriptProxyValidCallback(const char* webTag);
* @brief Registers the destroy callback.
*
* @param webTag The name of the web component.
* @param callback the destroy callback.
*
* @syscap SystemCapability.Web.Webview.Core
* @since 11
*/
void OH_NativeArkWeb_SetDestroyCallback(const char* webTag, NativeArkWeb_OnDestroyCallback callback);
* @brief Get the destroy callback.
*
* @param webTag The name of the web component.
* @return Return the destroy callback function registered. If the destroy callback
* function specified by the parameter webTag is not set,
* a null pointer is returned.
*
* @syscap SystemCapability.Web.Webview.Core
* @since 11
*/
NativeArkWeb_OnDestroyCallback OH_NativeArkWeb_GetDestroyCallback(const char* webTag);
* @brief Loads the data or URL.
* This function should be called on main thread.
*
* @param webTag The name of the web component.
* @param data A string encoded according to "Base64" or "URL", should not be NULL.
* @param mimeType Media type. For example: "text/html", should not be NULL.
* @param encoding Encoding type. For example: "UTF-8", should not be NULL.
* @param baseUrl A specified URL path ("http"/"https"/"data" protocol),
* which is assigned to window.origin by the Web component.
* @param historyUrl History URL. When it is not empty, it can be managed by
* history records to realize the back and forth function.
* @return LoadData result code.
* {@link ARKWEB_SUCCESS} load data success.
* {@link ARKWEB_INVALID_PARAM} Mandatory parameters are left unspecified or
* Incorrect parameter types or Parameter verification failed.
* {@link ARKWEB_INIT_ERROR} Initialization error, can't get a valid Web for the webTag.
* {@link ARKWEB_LIBRARY_OPEN_FAILURE} Failed to open the library.
* {@link ARKWEB_LIBRARY_SYMBOL_NOT_FOUND} The required symbol was not found in the library.
*
* @syscap SystemCapability.Web.Webview.Core
* @since 15
*/
ArkWeb_ErrorCode OH_NativeArkWeb_LoadData(const char* webTag,
const char* data,
const char* mimeType,
const char* encoding,
const char* baseUrl,
const char* historyUrl);
* @brief Registers a JavaScript object with callback methods, which may return values. This object will be injected
* into all frames of the current page, including all iframes, and will be accessible using the specified
* name in ArkWeb_ProxyObjectWithResult. The object will only be available in JavaScript after the next
* load or reload.
* These methods will be executed in the ArkWeb worker thread.
*
* @param webTag Name of the web component.
* @param proxyObject JavaScript object to register, the object has callback functions with return value.
* @param permission Optional JSON string(default is null) for JSBridge permission control,
* allowing URL whitelist configuration at object-level and method-level.
* @syscap SystemCapability.Web.Webview.Core
* @since 20
*/
void OH_NativeArkWeb_RegisterAsyncThreadJavaScriptProxy(const char* webTag,
const ArkWeb_ProxyObjectWithResult* proxyObject, const char* permission);
* @brief Sets whether to enable blankless loading. This API must be used together with the {@link OH_NativeArkWeb_GetBlanklessInfoWithKey}
* API.
*
* @permission ohos.permission.INTERNET and ohos.permission.GET_NETWORK_INFO
* @param webTag Name of the **Web** component.
* @param key Key value that uniquely identifies the page. The value must be the same as the key value of the {@link 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 {@link ArkWeb_BlanklessErrorCode} is returned and the frame insertion
* does not take effect.
* @param isStarted Whether to enable frame insertion. The value **true** indicates to enable frame insertion, and **
* false** indicates the opposite.
* The default value is **false**.
* @return Whether the API is successfully called. For details, see {@link ArkWeb_BlanklessErrorCode}.
* @since 20
*/
ArkWeb_BlanklessErrorCode OH_NativeArkWeb_SetBlanklessLoadingWithKey(const char* webTag,
const char* key,
bool isStarted);
* @brief Clears the blankless loading cache of the page with a specified key value.
*
* @param key The list of key values of pages cached in the blankless loading solution. These key values are
* specified in OH_NativeArkWeb_GetBlanklessInfoWithKey.
*
* The default value is the list of key values of all pages cached in the blankless loading solution.
*
* The key length cannot exceed 2048 characters, and the number of keys must be less than or equal to 100. The
* URL is the same as that input to the Web component during page loading.
*
* When the key length exceeds 2048 characters, the key does not take effect. When the number of keys exceeds
* 100, the first 100 keys are used. If this parameter is set to NULL, the default value is used.
*
* @param 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.
* @since 20
*/
void OH_NativeArkWeb_ClearBlanklessLoadingCache(const char* key[], uint32_t size);
* @brief 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 {@link ArkWeb_BlanklessInfo}
* . This API must be used together with the {@link OH_NativeArkWeb_SetBlanklessLoadingWithKey} API and must be called
* before the page loading API is triggered and after **WebViewController** is bound to the **Web** component.
*
* @permission ohos.permission.INTERNET and ohos.permission.GET_NETWORK_INFO
* @param webTag Name of the **Web** component.
* @param 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.
* @return 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.
* @since 20
*/
ArkWeb_BlanklessInfo OH_NativeArkWeb_GetBlanklessInfoWithKey(const char* webTag, const char* key);
* @brief 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.
*
* @param 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.
* @return 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.
* @since 20
*/
uint32_t OH_NativeArkWeb_SetBlanklessLoadingCacheCapacity(uint32_t capacity);
* @brief Ensure that all cookies currently accessible via the CookieManager API have been persisted to disk.
* If you want to use this interface in a non-UI thread, you need to initialize the CookieManager interface
* using OH_ArkWeb_GetNativeAPI first.
* @return Save cookie result code.
* {@link ARKWEB_SUCCESS} Save cookie success.
* {@link ARKWEB_COOKIE_SAVE_FAILED} Save cookie failed.
* {@link ARKWEB_COOKIE_MANAGER_INITIALIZE_FAILED} The CookieManager initialize failed.
* {@link ARKWEB_COOKIE_MANAGER_NOT_INITIALIZED} It is not allowed to call on a non-UI thread without
* initializing the CookieManager interface. please
* initialize the CookieManager interface using
* OH_ArkWeb_GetNativeAPI first.
* @since 20
*/
ArkWeb_ErrorCode OH_ArkWebCookieManager_SaveCookieSync();
* @brief Ensure that all cookies currently accessible via the CookieManager API have been persisted to disk.
* Without initializing the CookieManager interface, this call will automatically be executed on the UI thread.
* @param callback Callback execute when save cookie done.
* @since 20
*/
void OH_ArkWebCookieManager_SaveCookieAsync(OH_ArkWeb_OnCookieSaveCallback callback);
* 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.
*
* @param { ArkWebEngineVersion } webEngineVersion - ArkWeb kernel version.
* For details, see {@link ArkWebEngineVersion}.
* @since 20
*/
void OH_NativeArkWeb_SetActiveWebEngineVersion(ArkWebEngineVersion webEngineVersion);
* Obtains the current ArkWeb kernel version.
*
* @return The current ArkWeb kernel version defined by {@link ArkWebEngineVersion}.
* @since 20
*/
ArkWebEngineVersion OH_NativeArkWeb_GetActiveWebEngineVersion();
* Delays the initialization of the web engine. By default, the web engine is initialized when the CookieManager
* interface is called. By setting the 'lazy' parameter to true, the web engine will not be initialized when the
* CookieManager interface is called. Instead, the web engine will be initialized either when the web component is
* created or when initializeWebEngine is called.
* @param { bool } lazy - Controls whether to delay the initialization of the web engine.
* @since 22
*/
void OH_NativeArkWeb_LazyInitializeWebEngineInCookieManager(bool lazy);
* Checks whether the ArkWeb kernel used by the application is the evergreen kernel, that is, the latest kernel of the
* system.
*
* @return 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.
* @since 23
*/
bool OH_NativeArkWeb_IsActiveWebEngineEvergreen();
#ifdef __cplusplus
};
#endif
#endif