1 /* 2 * Copyright (c) 2024 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 Provide the definition of the C interface for the native ArkWeb. 21 * @since 12 22 */ 23 /** 24 * @file arkweb_type.h 25 * 26 * @brief Defines the common types for the native ArkWeb. 27 * @kit ArkWeb 28 * @library libohweb.so 29 * @syscap SystemCapability.Web.Webview.Core 30 * @since 12 31 */ 32 33 #ifndef ARKWEB_TYPE_H 34 #define ARKWEB_TYPE_H 35 36 #include <stddef.h> 37 #include <stdint.h> 38 39 #include "arkweb_error_code.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Defines the javascript bridge data type. 47 * 48 * @since 12 49 */ 50 typedef struct { 51 /** A buffer that contains data. */ 52 const uint8_t* buffer; 53 /** The size of the buffer. */ 54 size_t size; 55 } ArkWeb_JavaScriptBridgeData; 56 57 /** 58 * @brief Defines the data type carried in a ArkWeb_WebMessage. 59 * 60 * @since 12 61 */ 62 typedef enum ArkWeb_WebMessageType { 63 /** Represent error data */ 64 ARKWEB_NONE = 0, 65 /** The data carried in the ArkWeb_WebMessage is string. */ 66 ARKWEB_STRING, 67 /** The data carried in the ArkWeb_WebMessage is buffer(uint8_t). */ 68 ARKWEB_BUFFER 69 } ArkWeb_WebMessageType; 70 71 /** 72 * @brief Defines the data type carried in a ArkWeb_JavaScriptValue. 73 * 74 * @since 16 75 */ 76 typedef enum ArkWeb_JavaScriptValueType { 77 /** Represent error data */ 78 ARKWEB_JAVASCRIPT_NONE = 0, 79 /** The data carried in the ArkWeb_JavaScriptValue is string. */ 80 ARKWEB_JAVASCRIPT_STRING, 81 /** The data carried in the ArkWeb_JavaScriptValue is bool. */ 82 ARKWEB_JAVASCRIPT_BOOL 83 } ArkWeb_JavaScriptValueType; 84 85 /** 86 * @brief Defines the ArkWeb_WebMessage. 87 * 88 * @since 12 89 */ 90 typedef struct ArkWeb_WebMessage* ArkWeb_WebMessagePtr; 91 92 /** 93 * @brief Defines the ArkWeb_JavaScriptValuePtr. 94 * 95 * @since 16 96 */ 97 typedef struct ArkWeb_JavaScriptValue* ArkWeb_JavaScriptValuePtr; 98 99 /** 100 * @brief Defines the javascript callback of the native ArkWeb. 101 * 102 * @since 12 103 */ 104 typedef void (*ArkWeb_OnJavaScriptCallback)( 105 const char* webTag, const ArkWeb_JavaScriptBridgeData* data, void* userData); 106 107 /** 108 * @brief Defines the javascript proxy callback of the native ArkWeb. 109 * 110 * @since 12 111 */ 112 typedef void (*ArkWeb_OnJavaScriptProxyCallback)( 113 const char* webTag, const ArkWeb_JavaScriptBridgeData* dataArray, size_t arraySize, void* userData); 114 115 /** 116 * @brief Defines the JavaScript proxy callback of the native ArkWeb. 117 * 118 * @param webTag The name of the web component. 119 * @param dataArray The JavaScript bridge data array from HTML. 120 * @param arraySize The number of elements in the array. 121 * @param userData The data set by user. 122 * 123 * @since 16 124 */ 125 typedef ArkWeb_JavaScriptValuePtr (*ArkWeb_OnJavaScriptProxyCallbackWithResult)( 126 const char* webTag, const ArkWeb_JavaScriptBridgeData* dataArray, size_t arraySize, void* userData); 127 128 /** 129 * @brief Defines the component callback of the native ArkWeb. 130 * 131 * @since 12 132 */ 133 typedef void (*ArkWeb_OnComponentCallback)(const char* webTag, void* userData); 134 135 /** 136 * @brief Defines the scroll callback of the native ArkWeb. 137 * 138 * @param webTag The name of the web component. 139 * @param userData The data set by user. 140 * @param x X-axis scrolling offset. 141 * @param y Y-axis scrolling offset. 142 * 143 * @since 16 144 */ 145 typedef void (*ArkWeb_OnScrollCallback)(const char* webTag, void* userData, double x, double y); 146 147 /** 148 * @brief Defines the ArkWeb_WebMessagePort that represent a HTML5 message port. 149 * 150 * @since 12 151 */ 152 typedef struct ArkWeb_WebMessagePort* ArkWeb_WebMessagePortPtr; 153 154 /** 155 * @brief Defines the callback to receive message from HTML. 156 * 157 * @param webTag The name of the web component. 158 * @param port The ArkWeb_WebMessagePort for registering the ArkWeb_OnMessageEventHandler. 159 * @param message The received ArkWeb_WebMessage. 160 * @param userData The data set by user. 161 * 162 * @since 12 163 */ 164 typedef void (*ArkWeb_OnMessageEventHandler)( 165 const char* webTag, const ArkWeb_WebMessagePortPtr port, const ArkWeb_WebMessagePtr message, void* userData); 166 167 /** 168 * @brief Defines the javascript object. 169 * 170 * @since 12 171 */ 172 typedef struct { 173 /** A piece of javascript code. */ 174 const uint8_t* buffer; 175 /** The size of the javascript code. */ 176 size_t size; 177 /** Callbacks execute JavaScript script results. */ 178 ArkWeb_OnJavaScriptCallback callback; 179 /** The user data to set. */ 180 void* userData; 181 } ArkWeb_JavaScriptObject; 182 183 /** 184 * @brief Defines the javascript proxy registered method object. 185 * 186 * @since 12 187 */ 188 typedef struct { 189 /** The method of the application side JavaScript object participating in the registration. */ 190 const char* methodName; 191 /** The callback function registered by developer is called back when HTML side uses. */ 192 ArkWeb_OnJavaScriptProxyCallback callback; 193 /** The user data to set. */ 194 void* userData; 195 } ArkWeb_ProxyMethod; 196 197 /** 198 * @brief Defines the JavaScript proxy method with a return value. 199 * 200 * @since 16 201 */ 202 typedef struct { 203 /** The method of the application side JavaScript object participating in the registration. */ 204 const char* methodName; 205 /** The callback function with a return value registered by developer is called back when HTML side uses. */ 206 ArkWeb_OnJavaScriptProxyCallbackWithResult callback; 207 /** The user data to set. */ 208 void* userData; 209 } ArkWeb_ProxyMethodWithResult; 210 211 /** 212 * @brief Defines the javascript proxy registered object. 213 * 214 * @since 12 215 */ 216 typedef struct { 217 /** The name of the registered object. */ 218 const char* objName; 219 /** The javascript proxy registered method object list */ 220 const ArkWeb_ProxyMethod* methodList; 221 /** The size of the methodList. */ 222 size_t size; 223 } ArkWeb_ProxyObject; 224 225 /** 226 * @brief Defines the JavaScript proxy registered object with methodList that has a return value. 227 * 228 * @since 16 229 */ 230 typedef struct { 231 /** The name of the registered object. */ 232 const char* objName; 233 /** The JavaScript proxy registered method object list with a callback function that has a return value */ 234 const ArkWeb_ProxyMethodWithResult* methodList; 235 /** The size of the methodList. */ 236 size_t size; 237 } ArkWeb_ProxyObjectWithResult; 238 239 /** 240 * @brief Defines the controller API for native ArkWeb. 241 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 242 * whether the function structure has a corresponding function pointer to avoid crash 243 * caused by mismatch between the SDK and the device ROM. 244 * Use OH_ArkWeb_GetNativeAPI in the UI thread to obtain the Controller-related interface cluster. 245 * 246 * @since 12 247 */ 248 typedef struct { 249 /** The ArkWeb_ControllerAPI struct size. */ 250 size_t size; 251 /** Load a piece of code and execute JS code in the context of the currently displayed page. */ 252 void (*runJavaScript)(const char* webTag, const ArkWeb_JavaScriptObject* javascriptObject); 253 /** Register the JavaScript object and method list. */ 254 void (*registerJavaScriptProxy)(const char* webTag, const ArkWeb_ProxyObject* proxyObject); 255 /** Deletes the registered object which th given name. */ 256 void (*deleteJavaScriptRegister)(const char* webTag, const char* objName); 257 /** Refresh the current web page. */ 258 void (*refresh)(const char* webTag); 259 /** Register the JavaScript object and async method list. */ 260 void (*registerAsyncJavaScriptProxy)(const char* webTag, const ArkWeb_ProxyObject* proxyObject); 261 /** 262 * @brief Creates a message channel to communicate with HTML and returns 263 * the message ports representing the message channel endpoints. 264 * 265 * @param webTag The name of the web component. 266 * @param size The quantity of message ports. 267 */ 268 ArkWeb_WebMessagePortPtr* (*createWebMessagePorts)(const char* webTag, size_t* size); 269 270 /** 271 * @brief Destroy message ports. 272 * 273 * @param ports Address of the message ports array pointer. 274 * @param size The quantity of message ports. 275 */ 276 void (*destroyWebMessagePorts)(ArkWeb_WebMessagePortPtr** ports, size_t size); 277 278 /** 279 * @brief Post message ports to main frame. 280 * 281 * @param webTag The name of the web component. 282 * @param name Name of the message to be sent. 283 * @param size The quantity of message ports. 284 * @param url Indicates the URI for receiving the message. 285 * @return Post web message result code. 286 * {@link ARKWEB_SUCCESS} post web message success. 287 * {@link ARKWEB_INVALID_PARAM} the parameter verification fails. 288 * {@link ARKWEB_INIT_ERROR} no web associated with this webTag. 289 */ 290 ArkWeb_ErrorCode (*postWebMessage)( 291 const char* webTag, const char* name, ArkWeb_WebMessagePortPtr* webMessagePorts, size_t size, const char* url); 292 293 /** 294 * @brief Get the url of the last frame that calls the JavaScriptProxy. 295 * This should be call on the thread which JavaScriptProxy called. 296 * 297 * @return The url of the last frame that calls the JavaScriptProxy. 298 * @since 14 299 */ 300 const char* (*getLastJavascriptProxyCallingFrameUrl)(); 301 302 /** 303 * @brief Register the JavaScript object and method list, the method is callback function that has a return value. 304 * 305 * @param webTag The name of the web component. 306 * @param proxyObject The JavaScript object to register, the object has callback functions with return value. 307 * @param permission The JSON string, which defaults to null, is used to configure the permission control for 308 * JSBridge, allowing for the definition of URL whitelists at the object and method levels. 309 * 310 * @since 16 311 */ 312 void (*registerJavaScriptProxyEx)(const char* webTag, const ArkWeb_ProxyObjectWithResult* proxyObject, 313 const char* permission); 314 315 /** 316 * @brief Register the JavaScript object and async method list. 317 * 318 * @param webTag The name of the web component. 319 * @param proxyObject The JavaScript object to register. 320 * @param permission The JSON string, which defaults to null, is used to configure the permission control 321 * for JSBridge, allowing for the definition of URL whitelists at the object and method levels. 322 * 323 * @since 16 324 */ 325 void (*registerAsyncJavaScriptProxyEx)(const char* webTag, const ArkWeb_ProxyObject* proxyObject, 326 const char* permission); 327 } ArkWeb_ControllerAPI; 328 329 /** 330 * @brief Defines the component API for native ArkWeb. 331 * 332 * @since 12 333 */ 334 typedef struct { 335 /** The ArkWeb_ComponentAPI struct size. */ 336 size_t size; 337 /** Register the OnControllerAttached callback. */ 338 void (*onControllerAttached)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 339 /** Register the OnPageBegin callback. */ 340 void (*onPageBegin)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 341 /** Register the OnPageEnd callback. */ 342 void (*onPageEnd)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 343 /** Register the OnDestroy callback. */ 344 void (*onDestroy)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 345 } ArkWeb_ComponentAPI; 346 347 /** 348 * @brief Defines the web message API for native ArkWeb. 349 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 350 * whether the function structure has a corresponding function pointer to avoid crash 351 * caused by mismatch between the SDK and the device ROM. 352 * Use OH_ArkWeb_GetNativeAPI in the UI thread to obtain the WebMessagePort-related interface cluster. 353 * 354 * @since 12 355 */ 356 typedef struct { 357 /** The ArkWeb_WebMessagePortAPI struct size. */ 358 size_t size; 359 /** 360 * @brief Post message to HTML. 361 * 362 * @param webMessagePort The ArkWeb_WebMessagePort. 363 * @param webTag The name of the web component. 364 * @param webMessage The ArkWeb_WebMessage to send. 365 * @return Post message result code. 366 * {@link ARKWEB_SUCCESS} post message success. 367 * {@link ARKWEB_INVALID_PARAM} the parameter verification fails. 368 * {@link ARKWEB_INIT_ERROR} no web associated with this webTag. 369 */ 370 ArkWeb_ErrorCode (*postMessage)( 371 const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag, const ArkWeb_WebMessagePtr webMessage); 372 /** 373 * @brief Close the message port. 374 * 375 * @param webMessagePort The ArkWeb_WebMessagePort. 376 * @param webTag The name of the web component. 377 */ 378 void (*close)(const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag); 379 /** 380 * @brief Set a callback to receive message from HTML. 381 * 382 * @param webMessagePort The ArkWeb_WebMessagePort. 383 * @param webTag The name of the web component. 384 * @param messageEventHandler The handler to receive message from HTML. 385 * @param userData The data set by user. 386 */ 387 void (*setMessageEventHandler)(const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag, 388 ArkWeb_OnMessageEventHandler messageEventHandler, void* userData); 389 } ArkWeb_WebMessagePortAPI; 390 391 /** 392 * @brief Defines the web message data API for native ArkWeb. 393 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 394 * whether the function structure has a corresponding function pointer to avoid crash 395 * caused by mismatch between the SDK and the device ROM. 396 * Use OH_ArkWeb_GetNativeAPI in the UI thread to obtain the WebMessage-related interface cluster. 397 * 398 * @since 12 399 */ 400 typedef struct { 401 /** The ArkWeb_WebMessageAPI struct size. */ 402 size_t size; 403 /** 404 * @brief Used to create a ArkWeb_WebMessage. 405 * 406 * @return The created ArkWeb_WebMessage, destroy it through 407 * destroyWebMessage after it is no longer used. 408 */ 409 ArkWeb_WebMessagePtr (*createWebMessage)(); 410 /** 411 * @brief Used to destroy a ArkWeb_WebMessage. 412 * 413 * @param webMessage The ArkWeb_WebMessage to destroy. 414 */ 415 void (*destroyWebMessage)(ArkWeb_WebMessagePtr* webMessage); 416 /** 417 * @brief Set the type of ArkWeb_WebMessage. 418 * 419 * @param webMessage The ArkWeb_WebMessage. 420 * @param type The type of ArkWeb_WebMessage. 421 */ 422 void (*setType)(ArkWeb_WebMessagePtr webMessage, ArkWeb_WebMessageType type); 423 /** 424 * @brief Get the type of ArkWeb_WebMessage. 425 * 426 * @param webMessage The ArkWeb_WebMessage. 427 * @return The type of ArkWeb_WebMessage. 428 */ 429 ArkWeb_WebMessageType (*getType)(ArkWeb_WebMessagePtr webMessage); 430 /** 431 * @brief Set the data of ArkWeb_WebMessage. 432 * 433 * @param webMessage The ArkWeb_WebMessage. 434 * @param data The data of ArkWeb_WebMessage. 435 * @param dataLength The length of data. 436 */ 437 void (*setData)(ArkWeb_WebMessagePtr webMessage, void* data, size_t dataLength); 438 /** 439 * @brief Get the data of ArkWeb_WebMessage. 440 * 441 * @param webMessage The ArkWeb_WebMessage. 442 * @param dataLength The length of data. 443 * @return The data of ArkWeb_WebMessage. 444 */ 445 void* (*getData)(ArkWeb_WebMessagePtr webMessage, size_t* dataLength); 446 } ArkWeb_WebMessageAPI; 447 448 /** 449 * @brief Defines the native CookieManager API for ArkWeb. 450 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 451 * whether the function structure has a corresponding function pointer to avoid crash 452 * caused by mismatch between the SDK and the device ROM. 453 * Use OH_ArkWeb_GetNativeAPI in the UI thread to obtain the CookieManager-related interface cluster. 454 * 455 * @since 12 456 */ 457 typedef struct { 458 /** The ArkWeb_CookieManagerAPI struct size. */ 459 size_t size; 460 461 /** 462 * @brief Obtains the cookie value corresponding to a specified URL. 463 * 464 * @param url URL to which the cookie to be obtained belongs. A complete URL is recommended. 465 * @param incognito True indicates that the memory cookies of the webview in privacy mode are obtained, 466 * and false indicates that cookies in non-privacy mode are obtained. 467 * @param includeHttpOnly If true HTTP-only cookies will also be included in the cookieValue. 468 * @param cookieValue Get the cookie value corresponding to the URL. 469 * @return Fetch cookie result code. 470 * {@link ARKWEB_SUCCESS} fetch cookie success. 471 * {@link ARKWEB_INVALID_URL} invalid url. 472 * {@link ARKWEB_INVALID_PARAM} cookieValue is nullptr. 473 */ 474 ArkWeb_ErrorCode (*fetchCookieSync)(const char* url, bool incognito, bool includeHttpOnly, char** cookieValue); 475 476 /** 477 * @brief Sets the cookie value for a specified URL. 478 * 479 * @param url Specifies the URL to which the cookie belongs. A complete URL is recommended. 480 * @param cookieValue The value of the cookie to be set. 481 * @param incognito True indicates that cookies of the corresponding URL are set in privacy mode, 482 * and false indicates that cookies of the corresponding URL are set in non-privacy mode. 483 * @param includeHttpOnly If true, HTTP-only cookies can also be overwritten. 484 * @return Config cookie result code. 485 * {@link ARKWEB_SUCCESS} config cookie success. 486 * {@link ARKWEB_INVALID_URL} invalid url. 487 * {@link ARKWEB_INVALID_COOKIE_VALUE} invalid cookie value. 488 */ 489 ArkWeb_ErrorCode (*configCookieSync)(const char* url, 490 const char* cookieValue, bool incognito, bool includeHttpOnly); 491 492 /** 493 * @brief Check whether cookies exist. 494 * 495 * @param incognito True indicates whether cookies exist in privacy mode, 496 * and false indicates whether cookies exist in non-privacy mode. 497 * @return True indicates that the cookie exists, and false indicates that the cookie does not exist. 498 */ 499 bool (*existCookies)(bool incognito); 500 501 /** 502 * @brief Clear all cookies. 503 * 504 * @param incognito True indicates that all memory cookies of the webview are cleared in privacy mode, 505 * and false indicates that persistent cookies in non-privacy mode are cleared. 506 */ 507 void (*clearAllCookiesSync)(bool incognito); 508 509 /** 510 * @brief Clear all session cookies. 511 */ 512 void (*clearSessionCookiesSync)(); 513 } ArkWeb_CookieManagerAPI; 514 515 /** 516 * @brief Defines the native JavaScriptValue API for ArkWeb. 517 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 518 * whether the function structure has a corresponding function pointer to avoid crash 519 * caused by mismatch between the SDK and the device ROM. 520 * 521 * @since 16 522 */ 523 typedef struct { 524 /** The ArkWeb_JavaScriptValueAPI struct size. */ 525 size_t size; 526 527 /** 528 * @brief Create the JavaScript value responding to HTML. 529 * 530 * @param type The type of ArkWeb_JavaScriptValue. 531 * @param data The data buffer of ArkWeb_JavaScriptValue. 532 * @param dataLength The length of data buffer. 533 * @return ArkWeb_JavaScriptValuePtr created by ArkWeb, the memory of ArkWeb_JavaScriptValue 534 * is managed by ArkWeb itself. 535 */ 536 ArkWeb_JavaScriptValuePtr (*createJavaScriptValue)(ArkWeb_JavaScriptValueType type, void* data, size_t dataLength); 537 } ArkWeb_JavaScriptValueAPI; 538 539 /** 540 * @brief Check whether the member variables of the current struct exist. 541 * 542 * @since 12 543 */ 544 #define ARKWEB_MEMBER_EXISTS(s, f) \ 545 ((intptr_t) & ((s)->f) - (intptr_t)(s) + sizeof((s)->f) <= *reinterpret_cast<size_t*>(s)) 546 547 /** 548 * @brief Return false if the struct member does not exist, otherwise true. 549 * 550 * @since 12 551 */ 552 #define ARKWEB_MEMBER_MISSING(s, f) (!ARKWEB_MEMBER_EXISTS(s, f) || !((s)->f)) 553 554 #ifdef __cplusplus 555 } 556 #endif 557 #endif // ARKWEB_TYPE_H