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 18 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 18 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 18 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 18 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 18 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 18 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 * 245 * @since 12 246 */ 247 typedef struct { 248 /** The ArkWeb_ControllerAPI struct size. */ 249 size_t size; 250 /** Load a piece of code and execute JS code in the context of the currently displayed page. */ 251 void (*runJavaScript)(const char* webTag, const ArkWeb_JavaScriptObject* javascriptObject); 252 /** Register the JavaScript object and method list. */ 253 void (*registerJavaScriptProxy)(const char* webTag, const ArkWeb_ProxyObject* proxyObject); 254 /** Deletes the registered object which th given name. */ 255 void (*deleteJavaScriptRegister)(const char* webTag, const char* objName); 256 /** Refresh the current web page. */ 257 void (*refresh)(const char* webTag); 258 /** Register the JavaScript object and async method list. */ 259 void (*registerAsyncJavaScriptProxy)(const char* webTag, const ArkWeb_ProxyObject* proxyObject); 260 /** 261 * @brief Creates a message channel to communicate with HTML and returns 262 * the message ports representing the message channel endpoints. 263 * 264 * @param webTag The name of the web component. 265 * @param size The quantity of message ports. 266 */ 267 ArkWeb_WebMessagePortPtr* (*createWebMessagePorts)(const char* webTag, size_t* size); 268 269 /** 270 * @brief Destroy message ports. 271 * 272 * @param ports Address of the message ports array pointer. 273 * @param size The quantity of message ports. 274 */ 275 void (*destroyWebMessagePorts)(ArkWeb_WebMessagePortPtr** ports, size_t size); 276 277 /** 278 * @brief Post message ports to main frame. 279 * 280 * @param webTag The name of the web component. 281 * @param name Name of the message to be sent. 282 * @param size The quantity of message ports. 283 * @param url Indicates the URI for receiving the message. 284 * @return Post web message result code. 285 * {@link ARKWEB_SUCCESS} post web message success. 286 * {@link ARKWEB_INVALID_PARAM} the parameter verification fails. 287 * {@link ARKWEB_INIT_ERROR} no web associated with this webTag. 288 */ 289 ArkWeb_ErrorCode (*postWebMessage)( 290 const char* webTag, const char* name, ArkWeb_WebMessagePortPtr* webMessagePorts, size_t size, const char* url); 291 292 /** 293 * @brief Get the url of the last frame that calls the JavaScriptProxy. 294 * This should be call on the thread which JavaScriptProxy called. 295 * 296 * @return The url of the last frame that calls the JavaScriptProxy. 297 * @since 14 298 */ 299 const char* (*getLastJavascriptProxyCallingFrameUrl)(); 300 301 /** 302 * @brief Register the JavaScript object and method list, the method is callback function that has a return value. 303 * 304 * @param webTag The name of the web component. 305 * @param proxyObject The JavaScript object to register, the object has callback functions with return value. 306 * @param permission The JSON string, which defaults to null, is used to configure the permission control for 307 * JSBridge, allowing for the definition of URL whitelists at the object and method levels. 308 * 309 * @since 18 310 */ 311 void (*registerJavaScriptProxyEx)(const char* webTag, const ArkWeb_ProxyObjectWithResult* proxyObject, 312 const char* permission); 313 314 /** 315 * @brief Register the JavaScript object and async method list. 316 * 317 * @param webTag The name of the web component. 318 * @param proxyObject The JavaScript object to register. 319 * @param permission The JSON string, which defaults to null, is used to configure the permission control 320 * for JSBridge, allowing for the definition of URL whitelists at the object and method levels. 321 * 322 * @since 18 323 */ 324 void (*registerAsyncJavaScriptProxyEx)(const char* webTag, const ArkWeb_ProxyObject* proxyObject, 325 const char* permission); 326 } ArkWeb_ControllerAPI; 327 328 /** 329 * @brief Defines the component API for native ArkWeb. 330 * 331 * @since 12 332 */ 333 typedef struct { 334 /** The ArkWeb_ComponentAPI struct size. */ 335 size_t size; 336 /** Register the OnControllerAttached callback. */ 337 void (*onControllerAttached)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 338 /** Register the OnPageBegin callback. */ 339 void (*onPageBegin)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 340 /** Register the OnPageEnd callback. */ 341 void (*onPageEnd)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 342 /** Register the OnDestroy callback. */ 343 void (*onDestroy)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 344 } ArkWeb_ComponentAPI; 345 346 /** 347 * @brief Defines the web message API for native ArkWeb. 348 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 349 * whether the function structure has a corresponding function pointer to avoid crash 350 * caused by mismatch between the SDK and the device ROM. 351 * 352 * @since 12 353 */ 354 typedef struct { 355 /** The ArkWeb_WebMessagePortAPI struct size. */ 356 size_t size; 357 /** 358 * @brief Post message to HTML. 359 * 360 * @param webMessagePort The ArkWeb_WebMessagePort. 361 * @param webTag The name of the web component. 362 * @param webMessage The ArkWeb_WebMessage to send. 363 * @return Post message result code. 364 * {@link ARKWEB_SUCCESS} post message success. 365 * {@link ARKWEB_INVALID_PARAM} the parameter verification fails. 366 * {@link ARKWEB_INIT_ERROR} no web associated with this webTag. 367 */ 368 ArkWeb_ErrorCode (*postMessage)( 369 const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag, const ArkWeb_WebMessagePtr webMessage); 370 /** 371 * @brief Close the message port. 372 * 373 * @param webMessagePort The ArkWeb_WebMessagePort. 374 * @param webTag The name of the web component. 375 */ 376 void (*close)(const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag); 377 /** 378 * @brief Set a callback to receive message from HTML. 379 * 380 * @param webMessagePort The ArkWeb_WebMessagePort. 381 * @param webTag The name of the web component. 382 * @param messageEventHandler The handler to receive message from HTML. 383 * @param userData The data set by user. 384 */ 385 void (*setMessageEventHandler)(const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag, 386 ArkWeb_OnMessageEventHandler messageEventHandler, void* userData); 387 } ArkWeb_WebMessagePortAPI; 388 389 /** 390 * @brief Defines the web message data API for native ArkWeb. 391 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 392 * whether the function structure has a corresponding function pointer to avoid crash 393 * caused by mismatch between the SDK and the device ROM. 394 * 395 * @since 12 396 */ 397 typedef struct { 398 /** The ArkWeb_WebMessageAPI struct size. */ 399 size_t size; 400 /** 401 * @brief Used to create a ArkWeb_WebMessage. 402 * 403 * @return The created ArkWeb_WebMessage, destroy it through 404 * destroyWebMessage after it is no longer used. 405 */ 406 ArkWeb_WebMessagePtr (*createWebMessage)(); 407 /** 408 * @brief Used to destroy a ArkWeb_WebMessage. 409 * 410 * @param webMessage The ArkWeb_WebMessage to destroy. 411 */ 412 void (*destroyWebMessage)(ArkWeb_WebMessagePtr* webMessage); 413 /** 414 * @brief Set the type of ArkWeb_WebMessage. 415 * 416 * @param webMessage The ArkWeb_WebMessage. 417 * @param type The type of ArkWeb_WebMessage. 418 */ 419 void (*setType)(ArkWeb_WebMessagePtr webMessage, ArkWeb_WebMessageType type); 420 /** 421 * @brief Get the type of ArkWeb_WebMessage. 422 * 423 * @param webMessage The ArkWeb_WebMessage. 424 * @return The type of ArkWeb_WebMessage. 425 */ 426 ArkWeb_WebMessageType (*getType)(ArkWeb_WebMessagePtr webMessage); 427 /** 428 * @brief Set the data of ArkWeb_WebMessage. 429 * 430 * @param webMessage The ArkWeb_WebMessage. 431 * @param data The data of ArkWeb_WebMessage. 432 * @param dataLength The length of data. 433 */ 434 void (*setData)(ArkWeb_WebMessagePtr webMessage, void* data, size_t dataLength); 435 /** 436 * @brief Get the data of ArkWeb_WebMessage. 437 * 438 * @param webMessage The ArkWeb_WebMessage. 439 * @param dataLength The length of data. 440 * @return The data of ArkWeb_WebMessage. 441 */ 442 void* (*getData)(ArkWeb_WebMessagePtr webMessage, size_t* dataLength); 443 } ArkWeb_WebMessageAPI; 444 445 /** 446 * @brief Defines the native CookieManager API for ArkWeb. 447 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 448 * whether the function structure has a corresponding function pointer to avoid crash 449 * caused by mismatch between the SDK and the device ROM. 450 * 451 * @since 12 452 */ 453 typedef struct { 454 /** The ArkWeb_CookieManagerAPI struct size. */ 455 size_t size; 456 457 /** 458 * @brief Obtains the cookie value corresponding to a specified URL. 459 * 460 * @param url URL to which the cookie to be obtained belongs. A complete URL is recommended. 461 * @param incognito True indicates that the memory cookies of the webview in privacy mode are obtained, 462 * and false indicates that cookies in non-privacy mode are obtained. 463 * @param includeHttpOnly If true HTTP-only cookies will also be included in the cookieValue. 464 * @param cookieValue Get the cookie value corresponding to the URL. 465 * @return Fetch cookie result code. 466 * {@link ARKWEB_SUCCESS} fetch cookie success. 467 * {@link ARKWEB_INVALID_URL} invalid url. 468 * {@link ARKWEB_INVALID_PARAM} cookieValue is nullptr. 469 */ 470 ArkWeb_ErrorCode (*fetchCookieSync)(const char* url, bool incognito, bool includeHttpOnly, char** cookieValue); 471 472 /** 473 * @brief Sets the cookie value for a specified URL. 474 * 475 * @param url Specifies the URL to which the cookie belongs. A complete URL is recommended. 476 * @param cookieValue The value of the cookie to be set. 477 * @param incognito True indicates that cookies of the corresponding URL are set in privacy mode, 478 * and false indicates that cookies of the corresponding URL are set in non-privacy mode. 479 * @param includeHttpOnly If true, HTTP-only cookies can also be overwritten. 480 * @return Config cookie result code. 481 * {@link ARKWEB_SUCCESS} config cookie success. 482 * {@link ARKWEB_INVALID_URL} invalid url. 483 * {@link ARKWEB_INVALID_COOKIE_VALUE} invalid cookie value. 484 */ 485 ArkWeb_ErrorCode (*configCookieSync)(const char* url, 486 const char* cookieValue, bool incognito, bool includeHttpOnly); 487 488 /** 489 * @brief Check whether cookies exist. 490 * 491 * @param incognito True indicates whether cookies exist in privacy mode, 492 * and false indicates whether cookies exist in non-privacy mode. 493 * @return True indicates that the cookie exists, and false indicates that the cookie does not exist. 494 */ 495 bool (*existCookies)(bool incognito); 496 497 /** 498 * @brief Clear all cookies. 499 * 500 * @param incognito True indicates that all memory cookies of the webview are cleared in privacy mode, 501 * and false indicates that persistent cookies in non-privacy mode are cleared. 502 */ 503 void (*clearAllCookiesSync)(bool incognito); 504 505 /** 506 * @brief Clear all session cookies. 507 */ 508 void (*clearSessionCookiesSync)(); 509 } ArkWeb_CookieManagerAPI; 510 511 /** 512 * @brief Defines the native JavaScriptValue API for ArkWeb. 513 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 514 * whether the function structure has a corresponding function pointer to avoid crash 515 * caused by mismatch between the SDK and the device ROM. 516 * 517 * @since 18 518 */ 519 typedef struct { 520 /** The ArkWeb_JavaScriptValueAPI struct size. */ 521 size_t size; 522 523 /** 524 * @brief Create the JavaScript value responding to HTML. 525 * 526 * @param type The type of ArkWeb_JavaScriptValue. 527 * @param data The data buffer of ArkWeb_JavaScriptValue. 528 * @param dataLength The length of data buffer. 529 * @return ArkWeb_JavaScriptValuePtr created by ArkWeb, the memory of ArkWeb_JavaScriptValue 530 * is managed by ArkWeb itself. 531 */ 532 ArkWeb_JavaScriptValuePtr (*createJavaScriptValue)(ArkWeb_JavaScriptValueType type, void* data, size_t dataLength); 533 } ArkWeb_JavaScriptValueAPI; 534 535 /** 536 * @brief Check whether the member variables of the current struct exist. 537 * 538 * @since 12 539 */ 540 #define ARKWEB_MEMBER_EXISTS(s, f) \ 541 ((intptr_t) & ((s)->f) - (intptr_t)(s) + sizeof((s)->f) <= *reinterpret_cast<size_t*>(s)) 542 543 /** 544 * @brief Return false if the struct member does not exist, otherwise true. 545 * 546 * @since 12 547 */ 548 #define ARKWEB_MEMBER_MISSING(s, f) (!ARKWEB_MEMBER_EXISTS(s, f) || !((s)->f)) 549 550 #ifdef __cplusplus 551 } 552 #endif 553 #endif // ARKWEB_TYPE_H 554 /** @} */