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