1 /* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Web 18 * @{ 19 * 20 * @brief Provides APIs to use javascript proxy and run javascirpt code. 21 * @since 11 22 */ 23 /** 24 * @file native_interface_arkweb.h 25 * 26 * @brief Declares the APIs to use javascript proxy and run javascirpt code. 27 * @library libohweb.so 28 * @syscap SystemCapability.Web.Webview.Core 29 * @since 11 30 */ 31 #ifndef NATIVE_INTERFACE_ARKWEB_H 32 #define NATIVE_INTERFACE_ARKWEB_H 33 34 #include <cstdint> 35 36 #include "arkweb_error_code.h" 37 #include "arkweb_type.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /** 44 * @brief Defines the javascript callback of the web component. 45 * 46 * @since 11 47 */ 48 typedef void (*NativeArkWeb_OnJavaScriptCallback)(const char*); 49 50 /** 51 * @brief Defines the javascript proxy callback of the web component. 52 * 53 * @since 11 54 */ 55 typedef char* (*NativeArkWeb_OnJavaScriptProxyCallback)(const char** argv, int32_t argc); 56 57 /** 58 * @brief Defines the valid callback of the web component. 59 * 60 * @since 11 61 */ 62 typedef void (*NativeArkWeb_OnValidCallback)(const char*); 63 64 /** 65 * @brief Defines the destroy callback of the web component. 66 * 67 * @since 11 68 */ 69 typedef void (*NativeArkWeb_OnDestroyCallback)(const char*); 70 71 /** 72 * @brief Defines the callback of save cookie. 73 * @param errorCode {@link ARKWEB_SUCCESS} Save cookie success. 74 * {@link ARKWEB_COOKIE_MANAGER_INITIALIZE_FAILED} Cookie manager initialize failed. 75 * {@link ARKWEB_COOKIE_SAVE_FAILED} Save cookie failed. 76 * @since 20 77 */ 78 typedef void (*OH_ArkWeb_OnCookieSaveCallback)(ArkWeb_ErrorCode errorCode); 79 80 /** 81 * @brief Defines the blankless information. 82 * 83 * @since 20 84 */ 85 typedef struct { 86 /** The errCode of the blankless. */ 87 ArkWeb_BlanklessErrorCode errCode; 88 /** The estimated similarity of the history snapshots. */ 89 double similarity; 90 /** The loadingTime of the history loading. */ 91 int32_t loadingTime; 92 } ArkWeb_BlanklessInfo; 93 94 /** 95 * @brief ArkWeb Engine Version. 96 * 97 * @syscap SystemCapability.Web.Webview.Core 98 * @since 20 99 */ 100 typedef enum { 101 /** 102 * ArkWeb version SYSTEM_DEFAULT. 103 * @since 20 104 */ 105 SYSTEM_DEFAULT = 0, 106 /** 107 * ArkWeb M114 version. 108 * @since 20 109 */ 110 ARKWEB_M114 = 1, 111 /** 112 * ArkWeb M132 version. 113 * @since 20 114 */ 115 ARKWEB_M132 = 2, 116 117 /** 118 * ArkWeb Evergreen Web Engine, always use the new ArkWeb Engine. 119 * Evergreen Web Engine. 120 * @since 20 121 */ 122 ARKWEB_EVERGREEN = 99999, 123 } ArkWebEngineVersion; 124 125 /** 126 * @brief Loads a piece of code and execute JS code in the context of the currently displayed page. 127 * 128 * @param webTag The name of the web component. 129 * @param jsCode a piece of javascript code. 130 * @param callback Callbacks execute JavaScript script results. 131 * 132 * @syscap SystemCapability.Web.Webview.Core 133 * @since 11 134 */ 135 void OH_NativeArkWeb_RunJavaScript(const char* webTag, const char* jsCode, NativeArkWeb_OnJavaScriptCallback callback); 136 137 /** 138 * @brief Registers the JavaScript object and method list. 139 * 140 * @param webTag The name of the web component. 141 * @param objName The name of the registered object. 142 * @param methodList The method of the application side JavaScript object participating in the registration. 143 * @param callback The callback function registered by developer is called back when HTML side uses. 144 * @param size The size of the callback. 145 * @param needRefresh if web need refresh. 146 * 147 * @syscap SystemCapability.Web.Webview.Core 148 * @since 11 149 */ 150 void OH_NativeArkWeb_RegisterJavaScriptProxy(const char* webTag, const char* objName, const char** methodList, 151 NativeArkWeb_OnJavaScriptProxyCallback* callback, int32_t size, bool isNeedRefresh); 152 153 /** 154 * @brief Deletes the registered object which th given name. 155 * 156 * @param webTag The name of the web component. 157 * @param objName The name of the registered object. 158 * 159 * @syscap SystemCapability.Web.Webview.Core 160 * @since 11 161 */ 162 void OH_NativeArkWeb_UnregisterJavaScriptProxy(const char* webTag, const char* objName); 163 164 /** 165 * @brief Registers the valid callback. 166 * 167 * @param webTag The name of the web component. 168 * @param callback The callback in which we can register object. 169 * 170 * @syscap SystemCapability.Web.Webview.Core 171 * @since 11 172 */ 173 void OH_NativeArkWeb_SetJavaScriptProxyValidCallback(const char* webTag, NativeArkWeb_OnValidCallback callback); 174 175 /** 176 * @brief Get the valid callback. 177 * 178 * @param webTag The name of the web component. 179 * @return return the valid callback function registered. 180 * 181 * @syscap SystemCapability.Web.Webview.Core 182 * @since 11 183 */ 184 NativeArkWeb_OnValidCallback OH_NativeArkWeb_GetJavaScriptProxyValidCallback(const char* webTag); 185 186 /** 187 * @brief Registers the destroy callback. 188 * 189 * @param webTag The name of the web component. 190 * @param callback the destroy callback. 191 * 192 * @syscap SystemCapability.Web.Webview.Core 193 * @since 11 194 */ 195 void OH_NativeArkWeb_SetDestroyCallback(const char* webTag, NativeArkWeb_OnDestroyCallback callback); 196 197 /** 198 * @brief Get the destroy callback. 199 * 200 * @param webTag The name of the web component. 201 * @return return the destroy callback function registered. 202 * 203 * @syscap SystemCapability.Web.Webview.Core 204 * @since 11 205 */ 206 NativeArkWeb_OnDestroyCallback OH_NativeArkWeb_GetDestroyCallback(const char* webTag); 207 208 /** 209 * @brief Loads the data or URL. 210 * This function should be called on main thread. 211 * 212 * @param webTag The name of the web component. 213 * @param data A string encoded according to "Base64" or "URL", should not be NULL. 214 * @param mimeType Media type. For example: "text/html", should not be NULL. 215 * @param encoding Encoding type. For example: "UTF-8", should not be NULL. 216 * @param baseUrl A specified URL path ("http"/"https"/"data" protocol), 217 * which is assigned to window.origin by the Web component. 218 * @param historyUrl History URL. When it is not empty, it can be managed by 219 * history records to realize the back and forth function. 220 * @return LoadData result code. 221 * {@link ARKWEB_SUCCESS} load data success. 222 * {@link ARKWEB_INVALID_PARAM} Mandatory parameters are left unspecified or 223 * Incorrect parameter types or Parameter verification failed. 224 * {@link ARKWEB_INIT_ERROR} Initialization error, can't get a valid Web for the webTag. 225 * {@link ARKWEB_LIBRARY_OPEN_FAILURE} Failed to open the library. 226 * {@link ARKWEB_LIBRARY_SYMBOL_NOT_FOUND} The required symbol was not found in the library. 227 * 228 * @syscap SystemCapability.Web.Webview.Core 229 * @since 15 230 */ 231 ArkWeb_ErrorCode OH_NativeArkWeb_LoadData(const char* webTag, 232 const char* data, 233 const char* mimeType, 234 const char* encoding, 235 const char* baseUrl, 236 const char* historyUrl); 237 238 /** 239 * @brief Registers a JavaScript object with callback methods, which may return values. This object will be injected 240 * into all frames of the current page, including all iframes, and will be accessible using the specified 241 * name in ArkWeb_ProxyObjectWithResult. The object will only be available in JavaScript after the next 242 * load or reload. 243 * These methods will be executed in the ArkWeb worker thread. 244 * 245 * @param webTag Name of the web component. 246 * @param proxyObject JavaScript object to register, the object has callback functions with return value. 247 * @param permission Optional JSON string(default is null) for JSBridge permission control, 248 * allowing URL whitelist configuration at object-level and method-level. 249 * @syscap SystemCapability.Web.Webview.Core 250 * @since 20 251 */ 252 void OH_NativeArkWeb_RegisterAsyncThreadJavaScriptProxy(const char* webTag, 253 const ArkWeb_ProxyObjectWithResult* proxyObject, const char* permission); 254 255 /** 256 * @brief Obtains the prediction information about the blankless loading solution and enables the generation 257 * of the transition frame for the current loading. The application determines whether to enable the blankless 258 * loading solution based on the information. 259 * This API applies to pages in an applet or web application whose URLs are not fixed or cannot be uniquely 260 * identified. 261 * 262 * @param webTag webTag used when the webviewController is created. 263 * Default value: N/A. 264 * The value cannot be empty. 265 * When an invalid value is set, the error code is returned, and the API does not take effect. 266 * @param key Key value that uniquely identifies the current page. 267 * @return Return value of the ArkWeb_BlanklessInfo type. 268 * @since 20 269 */ 270 ArkWeb_BlanklessInfo OH_NativeArkWeb_GetBlanklessInfoWithKey(const char* webTag, const char* key); 271 272 /** 273 * @brief Sets whether to enable blankless page loading. This API must be used in pair with the 274 * OH_NativeArkWeb_GetBlanklessInfoWithKey API. 275 * 276 * @param webTag webTag used when the webviewController is created. 277 * @param key Key value that uniquely identifies the current page. It must be the same as the key value of the 278 * OH_NativeArkWeb_GetBlanklessInfoWithKey API. 279 * @param isStarted Whether to enable frame interpolation. The value true indicates to enable frame 280 * interpolation, and the value false indicates the opposite. 281 * The default value is false. 282 * The value can be true or false. 283 * Action for setting an invalid value: N/A. 284 * @return Whether the API is successfully called. For details, see ArkWeb_BlanklessErrorCode. 285 * @since 20 286 */ 287 ArkWeb_BlanklessErrorCode OH_NativeArkWeb_SetBlanklessLoadingWithKey(const char* webTag, 288 const char* key, 289 bool isStarted); 290 291 /** 292 * @brief Clears the blankless loading cache of the page with a specified key value. 293 * 294 * @param key The list of key values of pages cached in the blankless loading solution. These key values are 295 * specified in OH_NativeArkWeb_GetBlanklessInfoWithKey. 296 * The default value is the list of key values of all pages cached in the blankless loading solution. 297 * The key length cannot exceed 2048 characters, and the number of keys must be less than or equal to 100. The 298 * URL is the same as that input to the Web component during page loading. 299 * When the key length exceeds 2048 characters, the key does not take effect. When the number of keys exceeds 300 * 100, the first 100 keys are used. If this parameter is set to NULL, the default value is used. 301 * @param size Size of the key list. 302 * @since 20 303 */ 304 void OH_NativeArkWeb_ClearBlanklessLoadingCache(const char* key[], uint32_t size); 305 306 /** 307 * @brief Sets the cache capacity of the blankless loading solution and returns the value that takes effect. 308 * 309 * @param capacity Cache capacity, in MB. The maximum value is 100 MB. 310 * The default value is 30 MB. 311 * The value ranges from 0 to 100. If this parameter is set to 0, no cache capacity is available and the 312 * functionality is disabled globally. 313 * When the value is set to a number smaller than 0, the value 0 takes effect. When the value is set to a 314 * number greater than 100, the value 100 takes effect. 315 * @return The effective value that ranges from 0 MB to 100 MB. 316 * @since 20 317 */ 318 uint32_t OH_NativeArkWeb_SetBlanklessLoadingCacheCapacity(uint32_t capacity); 319 320 /** 321 * @brief Ensure that all cookies currently accessible via the CookieManager API have been persisted to disk. 322 * If you want to use this interface in a non-UI thread, you need to initialize the CookieManager interface 323 * using OH_ArkWeb_GetNativeAPI first. 324 * @return Save cookie result code. 325 * {@link ARKWEB_SUCCESS} Save cookie success. 326 * {@link ARKWEB_COOKIE_SAVE_FAILED} Save cookie failed. 327 * {@link ARKWEB_COOKIE_MANAGER_INITIALIZE_FAILED} The CookieManager initialize failed. 328 * {@link ARKWEB_COOKIE_MANAGER_NOT_INITIALIZED} It is not allowed to call on a non-UI thread without 329 * initializing the CookieManager interface. please 330 * initialize the CookieManager interface using 331 * OH_ArkWeb_GetNativeAPI first. 332 * @since 20 333 */ 334 ArkWeb_ErrorCode OH_ArkWebCookieManager_SaveCookieSync(); 335 336 /** 337 * @brief Ensure that all cookies currently accessible via the CookieManager API have been persisted to disk. 338 * Without initializing the CookieManager interface, this call will automatically be executed on the UI thread. 339 * @param callback Callback execute when save cookie done. 340 * @since 20 341 */ 342 void OH_ArkWebCookieManager_SaveCookieAsync(OH_ArkWeb_OnCookieSaveCallback callback); 343 344 /** 345 * Set active ArkWeb engine version. 346 * If the system does not support the specified version, it will not take effect. 347 * 348 * This is a global static API that must be called before initializeWebEngine, and it will have no effect if any 349 * Web components are loaded. 350 * @param { ArkWebEngineVersion } webEngineVersion - the WebEngineVersion 351 * @since 20 352 */ 353 void OH_NativeArkWeb_SetActiveWebEngineVersion(ArkWebEngineVersion webEngineVersion); 354 355 /** 356 * Get currently active ArkWeb engine version. 357 * @returns { ArkWebEngineVersion } Active ArkWeb Engine version as defined by WebEngineVersion 358 * @since 20 359 */ 360 ArkWebEngineVersion OH_NativeArkWeb_GetActiveWebEngineVersion(); 361 362 /** 363 * Check if the currently active ArkWeb engine is Evergreen. 364 * @returns { bool } true means the application is using the Evergreen Web Engine, false means not. 365 * @since 20 366 */ 367 bool OH_NativeArkWeb_IsActiveWebEngineEvergreen(); 368 369 #ifdef __cplusplus 370 }; 371 #endif 372 #endif // NATIVE_INTERFACE_ARKWEB_H 373