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 ArkWeb_WebMessage. 73 * 74 * @since 12 75 */ 76 typedef struct ArkWeb_WebMessage* ArkWeb_WebMessagePtr; 77 78 /** 79 * @brief Defines the javascript callback of the native ArkWeb. 80 * 81 * @since 12 82 */ 83 typedef void (*ArkWeb_OnJavaScriptCallback)( 84 const char* webTag, const ArkWeb_JavaScriptBridgeData* data, void* userData); 85 86 /** 87 * @brief Defines the javascript proxy callback of the native ArkWeb. 88 * 89 * @since 12 90 */ 91 typedef void (*ArkWeb_OnJavaScriptProxyCallback)( 92 const char* webTag, const ArkWeb_JavaScriptBridgeData* dataArray, size_t arraySize, void* userData); 93 94 /** 95 * @brief Defines the component callback of the native ArkWeb. 96 * 97 * @since 12 98 */ 99 typedef void (*ArkWeb_OnComponentCallback)(const char* webTag, void* userData); 100 101 /** 102 * @brief Defines the ArkWeb_WebMessagePort that represent a HTML5 message port. 103 * 104 * @since 12 105 */ 106 typedef struct ArkWeb_WebMessagePort* ArkWeb_WebMessagePortPtr; 107 108 /** 109 * @brief Defines the callback to receive message from HTML. 110 * 111 * @param webTag The name of the web component. 112 * @param port The ArkWeb_WebMessagePort for registering the ArkWeb_OnMessageEventHandler. 113 * @param message The received ArkWeb_WebMessage. 114 * @param userData The data set by user. 115 * 116 * @since 12 117 */ 118 typedef void (*ArkWeb_OnMessageEventHandler)( 119 const char* webTag, const ArkWeb_WebMessagePortPtr port, const ArkWeb_WebMessagePtr message, void* userData); 120 121 /** 122 * @brief Defines the javascript object. 123 * 124 * @since 12 125 */ 126 typedef struct { 127 /** A piece of javascript code. */ 128 const uint8_t* buffer; 129 /** The size of the javascript code. */ 130 size_t size; 131 /** Callbacks execute JavaScript script results. */ 132 ArkWeb_OnJavaScriptCallback callback; 133 /** The user data to set. */ 134 void* userData; 135 } ArkWeb_JavaScriptObject; 136 137 /** 138 * @brief Defines the javascript proxy registered method object. 139 * 140 * @since 12 141 */ 142 typedef struct { 143 /** The method of the application side JavaScript object participating in the registration. */ 144 const char* methodName; 145 /** The callback function registered by developer is called back when HTML side uses. */ 146 ArkWeb_OnJavaScriptProxyCallback callback; 147 /** The user data to set. */ 148 void* userData; 149 } ArkWeb_ProxyMethod; 150 151 /** 152 * @brief Defines the javascript proxy registered object. 153 * 154 * @since 12 155 */ 156 typedef struct { 157 /** The name of the registered object. */ 158 const char* objName; 159 /** The javascript proxy registered method object list */ 160 const ArkWeb_ProxyMethod* methodList; 161 /** The size of the methodList. */ 162 size_t size; 163 } ArkWeb_ProxyObject; 164 165 /** 166 * @brief Defines the controller API for native ArkWeb. 167 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 168 * whether the function structure has a corresponding function pointer to avoid crash 169 * caused by mismatch between the SDK and the device ROM. 170 * 171 * @since 12 172 */ 173 typedef struct { 174 /** The ArkWeb_ControllerAPI struct size. */ 175 size_t size; 176 /** Load a piece of code and execute JS code in the context of the currently displayed page. */ 177 void (*runJavaScript)(const char* webTag, const ArkWeb_JavaScriptObject* javascriptObject); 178 /** Register the JavaScript object and method list. */ 179 void (*registerJavaScriptProxy)(const char* webTag, const ArkWeb_ProxyObject* proxyObject); 180 /** Deletes the registered object which th given name. */ 181 void (*deleteJavaScriptRegister)(const char* webTag, const char* objName); 182 /** Refresh the current web page. */ 183 void (*refresh)(const char* webTag); 184 /** Register the JavaScript object and async method list. */ 185 void (*registerAsyncJavaScriptProxy)(const char* webTag, const ArkWeb_ProxyObject* proxyObject); 186 /** 187 * @brief Creates a message channel to communicate with HTML and returns 188 * the message ports representing the message channel endpoints. 189 * 190 * @param webTag The name of the web component. 191 * @param size The quantity of message ports. 192 */ 193 ArkWeb_WebMessagePortPtr* (*createWebMessagePorts)(const char* webTag, size_t* size); 194 195 /** 196 * @brief Destroy message ports. 197 * 198 * @param ports Address of the message ports array pointer. 199 * @param size The quantity of message ports. 200 */ 201 void (*destroyWebMessagePorts)(ArkWeb_WebMessagePortPtr** ports, size_t size); 202 203 /** 204 * @brief Post message ports to main frame. 205 * 206 * @param webTag The name of the web component. 207 * @param name Name of the message to be sent. 208 * @param size The quantity of message ports. 209 * @param url Indicates the URI for receiving the message. 210 * @return Post web message result code. 211 * {@link ARKWEB_SUCCESS} post web message success. 212 * {@link ARKWEB_INVALID_PARAM} the parameter verification fails. 213 * {@link ARKWEB_INIT_ERROR} no web associated with this webTag. 214 */ 215 ArkWeb_ErrorCode (*postWebMessage)( 216 const char* webTag, const char* name, ArkWeb_WebMessagePortPtr* webMessagePorts, size_t size, const char* url); 217 218 /** 219 * @brief Get the url of the last frame that calls the JavaScriptProxy. 220 * This should be call on the thread which JavaScriptProxy called. 221 * 222 * @return The url of the last frame that calls the JavaScriptProxy. 223 * @since 14 224 */ 225 const char* (*getLastJavascriptProxyCallingFrameUrl)(); 226 } ArkWeb_ControllerAPI; 227 228 /** 229 * @brief Defines the component API for native ArkWeb. 230 * 231 * @since 12 232 */ 233 typedef struct { 234 /** The ArkWeb_ComponentAPI struct size. */ 235 size_t size; 236 /** Register the OnControllerAttached callback. */ 237 void (*onControllerAttached)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 238 /** Register the OnPageBegin callback. */ 239 void (*onPageBegin)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 240 /** Register the OnPageEnd callback. */ 241 void (*onPageEnd)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 242 /** Register the OnDestroy callback. */ 243 void (*onDestroy)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 244 } ArkWeb_ComponentAPI; 245 246 /** 247 * @brief Defines the web message API for native ArkWeb. 248 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 249 * whether the function structure has a corresponding function pointer to avoid crash 250 * caused by mismatch between the SDK and the device ROM. 251 * 252 * @since 12 253 */ 254 typedef struct { 255 /** The ArkWeb_WebMessagePortAPI struct size. */ 256 size_t size; 257 /** 258 * @brief Post message to HTML. 259 * 260 * @param webMessagePort The ArkWeb_WebMessagePort. 261 * @param webTag The name of the web component. 262 * @param webMessage The ArkWeb_WebMessage to send. 263 * @return Post message result code. 264 * {@link ARKWEB_SUCCESS} post message success. 265 * {@link ARKWEB_INVALID_PARAM} the parameter verification fails. 266 * {@link ARKWEB_INIT_ERROR} no web associated with this webTag. 267 */ 268 ArkWeb_ErrorCode (*postMessage)( 269 const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag, const ArkWeb_WebMessagePtr webMessage); 270 /** 271 * @brief Close the message port. 272 * 273 * @param webMessagePort The ArkWeb_WebMessagePort. 274 * @param webTag The name of the web component. 275 */ 276 void (*close)(const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag); 277 /** 278 * @brief Set a callback to receive message from HTML. 279 * 280 * @param webMessagePort The ArkWeb_WebMessagePort. 281 * @param webTag The name of the web component. 282 * @param messageEventHandler The handler to receive message from HTML. 283 * @param userData The data set by user. 284 */ 285 void (*setMessageEventHandler)(const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag, 286 ArkWeb_OnMessageEventHandler messageEventHandler, void* userData); 287 } ArkWeb_WebMessagePortAPI; 288 289 /** 290 * @brief Defines the web message data API for native ArkWeb. 291 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 292 * whether the function structure has a corresponding function pointer to avoid crash 293 * caused by mismatch between the SDK and the device ROM. 294 * 295 * @since 12 296 */ 297 typedef struct { 298 /** The ArkWeb_WebMessageAPI struct size. */ 299 size_t size; 300 /** 301 * @brief Used to create a ArkWeb_WebMessage. 302 * 303 * @return The created ArkWeb_WebMessage, destroy it through 304 * destroyWebMessage after it is no longer used. 305 */ 306 ArkWeb_WebMessagePtr (*createWebMessage)(); 307 /** 308 * @brief Used to destroy a ArkWeb_WebMessage. 309 * 310 * @param webMessage The ArkWeb_WebMessage to destroy. 311 */ 312 void (*destroyWebMessage)(ArkWeb_WebMessagePtr* webMessage); 313 /** 314 * @brief Set the type of ArkWeb_WebMessage. 315 * 316 * @param webMessage The ArkWeb_WebMessage. 317 * @param type The type of ArkWeb_WebMessage. 318 */ 319 void (*setType)(ArkWeb_WebMessagePtr webMessage, ArkWeb_WebMessageType type); 320 /** 321 * @brief Get the type of ArkWeb_WebMessage. 322 * 323 * @param webMessage The ArkWeb_WebMessage. 324 * @return The type of ArkWeb_WebMessage. 325 */ 326 ArkWeb_WebMessageType (*getType)(ArkWeb_WebMessagePtr webMessage); 327 /** 328 * @brief Set the data of ArkWeb_WebMessage. 329 * 330 * @param webMessage The ArkWeb_WebMessage. 331 * @param data The data of ArkWeb_WebMessage. 332 * @param dataLength The length of data. 333 */ 334 void (*setData)(ArkWeb_WebMessagePtr webMessage, void* data, size_t dataLength); 335 /** 336 * @brief Get the data of ArkWeb_WebMessage. 337 * 338 * @param webMessage The ArkWeb_WebMessage. 339 * @param dataLength The length of data. 340 * @return The data of ArkWeb_WebMessage. 341 */ 342 void* (*getData)(ArkWeb_WebMessagePtr webMessage, size_t* dataLength); 343 } ArkWeb_WebMessageAPI; 344 345 /** 346 * @brief Defines the native CookieManager API for ArkWeb. 347 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 348 * whether the function structure has a corresponding function pointer to avoid crash 349 * caused by mismatch between the SDK and the device ROM. 350 * 351 * @since 12 352 */ 353 typedef struct { 354 /** The ArkWeb_CookieManagerAPI struct size. */ 355 size_t size; 356 357 /** 358 * @brief Obtains the cookie value corresponding to a specified URL. 359 * 360 * @param url URL to which the cookie to be obtained belongs. A complete URL is recommended. 361 * @param incognito True indicates that the memory cookies of the webview in privacy mode are obtained, 362 * and false indicates that cookies in non-privacy mode are obtained. 363 * @param includeHttpOnly If true HTTP-only cookies will also be included in the cookieValue. 364 * @param cookieValue Get the cookie value corresponding to the URL. 365 * @return Fetch cookie result code. 366 * {@link ARKWEB_SUCCESS} fetch cookie success. 367 * {@link ARKWEB_INVALID_URL} invalid url. 368 * {@link ARKWEB_INVALID_PARAM} cookieValue is nullptr. 369 */ 370 ArkWeb_ErrorCode (*fetchCookieSync)(const char* url, bool incognito, bool includeHttpOnly, char** cookieValue); 371 372 /** 373 * @brief Sets the cookie value for a specified URL. 374 * 375 * @param url Specifies the URL to which the cookie belongs. A complete URL is recommended. 376 * @param cookieValue The value of the cookie to be set. 377 * @param incognito True indicates that cookies of the corresponding URL are set in privacy mode, 378 * and false indicates that cookies of the corresponding URL are set in non-privacy mode. 379 * @param includeHttpOnly If true, HTTP-only cookies can also be overwritten. 380 * @return Config cookie result code. 381 * {@link ARKWEB_SUCCESS} config cookie success. 382 * {@link ARKWEB_INVALID_URL} invalid url. 383 * {@link ARKWEB_INVALID_COOKIE_VALUE} invalid cookie value. 384 */ 385 ArkWeb_ErrorCode (*configCookieSync)(const char* url, 386 const char* cookieValue, bool incognito, bool includeHttpOnly); 387 388 /** 389 * @brief Check whether cookies exist. 390 * 391 * @param incognito True indicates whether cookies exist in privacy mode, 392 * and false indicates whether cookies exist in non-privacy mode. 393 * @return True indicates that the cookie exists, and false indicates that the cookie does not exist. 394 */ 395 bool (*existCookies)(bool incognito); 396 397 /** 398 * @brief Clear all cookies. 399 * 400 * @param incognito True indicates that all memory cookies of the webview are cleared in privacy mode, 401 * and false indicates that persistent cookies in non-privacy mode are cleared. 402 */ 403 void (*clearAllCookiesSync)(bool incognito); 404 405 /** 406 * @brief Clear all session cookies. 407 */ 408 void (*clearSessionCookiesSync)(); 409 } ArkWeb_CookieManagerAPI; 410 411 /** 412 * @brief Check whether the member variables of the current struct exist. 413 * 414 * @since 12 415 */ 416 #define ARKWEB_MEMBER_EXISTS(s, f) \ 417 ((intptr_t) & ((s)->f) - (intptr_t)(s) + sizeof((s)->f) <= *reinterpret_cast<size_t*>(s)) 418 419 /** 420 * @brief Return false if the struct member does not exist, otherwise true. 421 * 422 * @since 12 423 */ 424 #define ARKWEB_MEMBER_MISSING(s, f) (!ARKWEB_MEMBER_EXISTS(s, f) || !((s)->f)) 425 426 #ifdef __cplusplus 427 } 428 #endif 429 #endif // ARKWEB_TYPE_H