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 } ArkWeb_ControllerAPI; 218 219 /** 220 * @brief Defines the component API for native ArkWeb. 221 * 222 * @since 12 223 */ 224 typedef struct { 225 /** The ArkWeb_ComponentAPI struct size. */ 226 size_t size; 227 /** Register the OnControllerAttached callback. */ 228 void (*onControllerAttached)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 229 /** Register the OnPageBegin callback. */ 230 void (*onPageBegin)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 231 /** Register the OnPageEnd callback. */ 232 void (*onPageEnd)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 233 /** Register the OnDestroy callback. */ 234 void (*onDestroy)(const char* webTag, ArkWeb_OnComponentCallback callback, void* userData); 235 } ArkWeb_ComponentAPI; 236 237 /** 238 * @brief Defines the web message API for native ArkWeb. 239 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 240 * whether the function structure has a corresponding function pointer to avoid crash 241 * caused by mismatch between the SDK and the device ROM. 242 * 243 * @since 12 244 */ 245 typedef struct { 246 /** The ArkWeb_WebMessagePortAPI struct size. */ 247 size_t size; 248 /** 249 * @brief Post message to HTML. 250 * 251 * @param webMessagePort The ArkWeb_WebMessagePort. 252 * @param webTag The name of the web component. 253 * @param webMessage The ArkWeb_WebMessage to send. 254 * @return Post message result code. 255 * {@link ARKWEB_SUCCESS} post message success. 256 * {@link ARKWEB_INVALID_PARAM} the parameter verification fails. 257 * {@link ARKWEB_INIT_ERROR} no web associated with this webTag. 258 */ 259 ArkWeb_ErrorCode (*postMessage)( 260 const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag, const ArkWeb_WebMessagePtr webMessage); 261 /** 262 * @brief Close the message port. 263 * 264 * @param webMessagePort The ArkWeb_WebMessagePort. 265 * @param webTag The name of the web component. 266 */ 267 void (*close)(const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag); 268 /** 269 * @brief Set a callback to receive message from HTML. 270 * 271 * @param webMessagePort The ArkWeb_WebMessagePort. 272 * @param webTag The name of the web component. 273 * @param messageEventHandler The handler to receive message from HTML. 274 * @param userData The data set by user. 275 */ 276 void (*setMessageEventHandler)(const ArkWeb_WebMessagePortPtr webMessagePort, const char* webTag, 277 ArkWeb_OnMessageEventHandler messageEventHandler, void* userData); 278 } ArkWeb_WebMessagePortAPI; 279 280 /** 281 * @brief Defines the web message data API for native ArkWeb. 282 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 283 * whether the function structure has a corresponding function pointer to avoid crash 284 * caused by mismatch between the SDK and the device ROM. 285 * 286 * @since 12 287 */ 288 typedef struct { 289 /** The ArkWeb_WebMessageAPI struct size. */ 290 size_t size; 291 /** 292 * @brief Used to create a ArkWeb_WebMessage. 293 * 294 * @return The created ArkWeb_WebMessage, destroy it through 295 * destroyWebMessage after it is no longer used. 296 */ 297 ArkWeb_WebMessagePtr (*createWebMessage)(); 298 /** 299 * @brief Used to destroy a ArkWeb_WebMessage. 300 * 301 * @param webMessage The ArkWeb_WebMessage to destroy. 302 */ 303 void (*destroyWebMessage)(ArkWeb_WebMessagePtr* webMessage); 304 /** 305 * @brief Set the type of ArkWeb_WebMessage. 306 * 307 * @param webMessage The ArkWeb_WebMessage. 308 * @param type The type of ArkWeb_WebMessage. 309 */ 310 void (*setType)(ArkWeb_WebMessagePtr webMessage, ArkWeb_WebMessageType type); 311 /** 312 * @brief Get the type of ArkWeb_WebMessage. 313 * 314 * @param webMessage The ArkWeb_WebMessage. 315 * @return The type of ArkWeb_WebMessage. 316 */ 317 ArkWeb_WebMessageType (*getType)(ArkWeb_WebMessagePtr webMessage); 318 /** 319 * @brief Set the data of ArkWeb_WebMessage. 320 * 321 * @param webMessage The ArkWeb_WebMessage. 322 * @param data The data of ArkWeb_WebMessage. 323 * @param dataLength The length of data. 324 */ 325 void (*setData)(ArkWeb_WebMessagePtr webMessage, void* data, size_t dataLength); 326 /** 327 * @brief Get the data of ArkWeb_WebMessage. 328 * 329 * @param webMessage The ArkWeb_WebMessage. 330 * @param dataLength The length of data. 331 * @return The data of ArkWeb_WebMessage. 332 */ 333 void* (*getData)(ArkWeb_WebMessagePtr webMessage, size_t* dataLength); 334 } ArkWeb_WebMessageAPI; 335 336 /** 337 * @brief Defines the native CookieManager API for ArkWeb. 338 * Before invoking an API, you are advised to use ARKWEB_MEMBER_MISSING to check 339 * whether the function structure has a corresponding function pointer to avoid crash 340 * caused by mismatch between the SDK and the device ROM. 341 * 342 * @since 12 343 */ 344 typedef struct { 345 /** The ArkWeb_CookieManagerAPI struct size. */ 346 size_t size; 347 348 /** 349 * @brief Obtains the cookie value corresponding to a specified URL. 350 * 351 * @param url URL to which the cookie to be obtained belongs. A complete URL is recommended. 352 * @param incognito True indicates that the memory cookies of the webview in privacy mode are obtained, 353 * and false indicates that cookies in non-privacy mode are obtained. 354 * @param includeHttpOnly If true HTTP-only cookies will also be included in the cookieValue. 355 * @param cookieValue Get the cookie value corresponding to the URL. 356 * @return Fetch cookie result code. 357 * {@link ARKWEB_SUCCESS} fetch cookie success. 358 * {@link ARKWEB_INVALID_URL} invalid url. 359 * {@link ARKWEB_INVALID_PARAM} cookieValue is nullptr. 360 */ 361 ArkWeb_ErrorCode (*fetchCookieSync)(const char* url, bool incognito, bool includeHttpOnly, char** cookieValue); 362 363 /** 364 * @brief Sets the cookie value for a specified URL. 365 * 366 * @param url Specifies the URL to which the cookie belongs. A complete URL is recommended. 367 * @param cookieValue The value of the cookie to be set. 368 * @param incognito True indicates that cookies of the corresponding URL are set in privacy mode, 369 * and false indicates that cookies of the corresponding URL are set in non-privacy mode. 370 * @param includeHttpOnly If true, HTTP-only cookies can also be overwritten. 371 * @return Config cookie result code. 372 * {@link ARKWEB_SUCCESS} config cookie success. 373 * {@link ARKWEB_INVALID_URL} invalid url. 374 * {@link ARKWEB_INVALID_COOKIE_VALUE} invalid cookie value. 375 */ 376 ArkWeb_ErrorCode (*configCookieSync)(const char* url, 377 const char* cookieValue, bool incognito, bool includeHttpOnly); 378 379 /** 380 * @brief Check whether cookies exist. 381 * 382 * @param incognito True indicates whether cookies exist in privacy mode, 383 * and false indicates whether cookies exist in non-privacy mode. 384 * @return True indicates that the cookie exists, and false indicates that the cookie does not exist. 385 */ 386 bool (*existCookies)(bool incognito); 387 388 /** 389 * @brief Clear all cookies. 390 * 391 * @param incognito True indicates that all memory cookies of the webview are cleared in privacy mode, 392 * and false indicates that persistent cookies in non-privacy mode are cleared. 393 */ 394 void (*clearAllCookiesSync)(bool incognito); 395 396 /** 397 * @brief Clear all session cookies. 398 */ 399 void (*clearSessionCookiesSync)(); 400 } ArkWeb_CookieManagerAPI; 401 402 /** 403 * @brief Check whether the member variables of the current struct exist. 404 * 405 * @since 12 406 */ 407 #define ARKWEB_MEMBER_EXISTS(s, f) \ 408 ((intptr_t) & ((s)->f) - (intptr_t)(s) + sizeof((s)->f) <= *reinterpret_cast<size_t*>(s)) 409 410 /** 411 * @brief Return false if the struct member does not exist, otherwise true. 412 * 413 * @since 12 414 */ 415 #define ARKWEB_MEMBER_MISSING(s, f) (!ARKWEB_MEMBER_EXISTS(s, f) || !((s)->f)) 416 417 #ifdef __cplusplus 418 } 419 #endif 420 #endif // ARKWEB_TYPE_H