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 OH_CommonEvent 18 * @{ 19 * 20 * @brief Provides the APIs of common event service. 21 * 22 * @since 12 23 */ 24 /** 25 * @file oh_commonevent.h 26 * 27 * @brief Declares the APIs to subscribe and unsubscribe common event, and so on. 28 * 29 * @library libohcommonevent.so 30 * @kit BasicServicesKit 31 * @syscap SystemCapability.Notification.CommonEvent 32 * @since 12 33 * @version 1.0 34 */ 35 36 #ifndef OH_COMMONEVENT_H 37 #define OH_COMMONEVENT_H 38 39 #include <stddef.h> 40 #include <stdint.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @brief Defines error codes. 48 * 49 * @since 12 50 * @version 1.0 51 */ 52 typedef enum CommonEvent_ErrCode { 53 /** @error Execution successful. */ 54 COMMONEVENT_ERR_OK = 0, 55 56 /** @error permission verification failed. */ 57 COMMONEVENT_ERR_PERMISSION_ERROR = 201, 58 59 /** @error invalid input parameter. */ 60 COMMONEVENT_ERR_INVALID_PARAMETER = 401, 61 62 /** 63 * @error The common event send frequency too high. 64 * 65 * @since 20 66 */ 67 COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED = 1500003, 68 69 /** @error the application cannot send system common events. */ 70 COMMONEVENT_ERR_NOT_SYSTEM_SERVICE = 1500004, 71 72 /** @error IPC request failed to send. */ 73 COMMONEVENT_ERR_SENDING_REQUEST_FAILED = 1500007, 74 75 /** @error Common event service not init. */ 76 COMMONEVENT_ERR_INIT_UNDONE = 1500008, 77 78 /** @error Failed to obtain system parameters. */ 79 COMMONEVENT_ERR_OBTAIN_SYSTEM_PARAMS = 1500009, 80 81 /** @error The subscriber number exceed system specification */ 82 COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED = 1500010, 83 84 /** @error A memory allocation error occurs. */ 85 COMMONEVENT_ERR_ALLOC_MEMORY_FAILED = 1500011, 86 } CommonEvent_ErrCode; 87 88 /** 89 * @brief the information of the subscriber 90 * 91 * @since 12 92 */ 93 typedef struct CommonEvent_SubscribeInfo CommonEvent_SubscribeInfo; 94 95 /** 96 * @brief the subscriber of common event 97 * 98 * @since 12 99 */ 100 typedef void CommonEvent_Subscriber; 101 102 /** 103 * @brief the common event publish information containing content and attributes of the common event 104 * 105 * @since 18 106 */ 107 typedef struct CommonEvent_PublishInfo CommonEvent_PublishInfo; 108 109 /** 110 * @brief the data of the commonEvent callback 111 * 112 * @since 12 113 */ 114 typedef struct CommonEvent_RcvData CommonEvent_RcvData; 115 116 /** 117 * @brief The description of the parameters in a common event callback data. 118 * 119 * @since 12 120 */ 121 typedef void CommonEvent_Parameters; 122 123 /** 124 * @brief Common event callback. 125 * 126 * @param data common event callback data. 127 * @since 12 128 */ 129 typedef void (*CommonEvent_ReceiveCallback)(const CommonEvent_RcvData *data); 130 131 /** 132 * @brief Create subscribe information. 133 * 134 * @param events Indicates the subscribed events. 135 * @param eventsNum Indicates the subscribed events of number. 136 * @return Returns the CommonEvent_SubscribeInfo, if allocate memory failed, returns null. 137 * @since 12 138 */ 139 CommonEvent_SubscribeInfo* OH_CommonEvent_CreateSubscribeInfo(const char* events[], int32_t eventsNum); 140 141 /** 142 * @brief Set the permission of the subscribe information. 143 * 144 * @param info Indicates the subscribe information. 145 * @param permission Indicates the permission. 146 * @return Returns the error code. 147 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 148 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 149 * @since 12 150 */ 151 CommonEvent_ErrCode OH_CommonEvent_SetPublisherPermission(CommonEvent_SubscribeInfo* info, const char* permission); 152 153 /** 154 * @brief Set the bundleName of the subscribe information. 155 * 156 * @param info Indicates the subscribed events. 157 * @param bundleName Indicates the bundleName. 158 * @return Returns the error code. 159 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 160 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 161 * @since 12 162 */ 163 CommonEvent_ErrCode OH_CommonEvent_SetPublisherBundleName(CommonEvent_SubscribeInfo* info, const char* bundleName); 164 165 /** 166 * @brief Destroy the subscribe information. 167 * 168 * @param info Indicates the subscribe info. 169 * @since 12 170 */ 171 void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info); 172 173 /** 174 * @brief Create a subscriber. 175 * 176 * @param info Indicates the created subscribe Info. 177 * @param callback Indicates the received common event callback. 178 * @return Returns the CommonEvent_Subscriber, if allocate memory failed, returns null. 179 * @since 12 180 */ 181 CommonEvent_Subscriber* OH_CommonEvent_CreateSubscriber(const CommonEvent_SubscribeInfo* info, 182 CommonEvent_ReceiveCallback callback); 183 184 /** 185 * @brief Destory the subscriber. 186 * 187 * @param subscriber Indicates the created subscriber. 188 * @since 12 189 */ 190 void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber); 191 192 /** 193 * @brief Subscribe event by a subscriber. 194 * 195 * @param subscriber Indicates the subscriber. 196 * @return Returns the error code. 197 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 198 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid. 199 * Returns {@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED } if IPC request failed to send. 200 * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. 201 * Returns {@link COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED } if the subscriber number is exceeded. 202 * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED } if a memory allocation error occurs. 203 * @since 12 204 */ 205 CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber); 206 207 /** 208 * @brief Unsubscribe event by a subscriber. 209 * 210 * @param subscriber Indicates the subscriber. 211 * @return Returns the error code. 212 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 213 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid. 214 * Returns {@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED } if IPC request failed to send. 215 * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. 216 * @since 12 217 */ 218 CommonEvent_ErrCode OH_CommonEvent_UnSubscribe(const CommonEvent_Subscriber* subscriber); 219 220 /** 221 * @brief Get event name from callback data. 222 * 223 * @param rcvData Indicates the callback data. 224 * @return Returns the event name. 225 * @since 12 226 */ 227 const char* OH_CommonEvent_GetEventFromRcvData(const CommonEvent_RcvData* rcvData); 228 229 /** 230 * @brief Get event code from callback data. 231 * 232 * @param rcvData Indicates the callback data. 233 * @return Returns the event of code, default is 0. 234 * @since 12 235 */ 236 int32_t OH_CommonEvent_GetCodeFromRcvData(const CommonEvent_RcvData* rcvData); 237 238 /** 239 * @brief Get event data from callback data. 240 * 241 * @param rcvData Indicates the callback data. 242 * @return Returns the event of data, default is null. 243 * @since 12 244 */ 245 const char* OH_CommonEvent_GetDataStrFromRcvData(const CommonEvent_RcvData* rcvData); 246 247 /** 248 * @brief Get event bundlename from callback data. 249 * 250 * @param rcvData Indicates the callback data. 251 * @return Returns the event of bundlename, default is null. 252 * @since 12 253 */ 254 const char* OH_CommonEvent_GetBundleNameFromRcvData(const CommonEvent_RcvData* rcvData); 255 256 /** 257 * @brief Get event parameters data from callback data. 258 * 259 * @param rcvData Indicates the callback data. 260 * @return Returns the event parameters data, default is null. 261 * @since 12 262 */ 263 const CommonEvent_Parameters* OH_CommonEvent_GetParametersFromRcvData(const CommonEvent_RcvData* rcvData); 264 265 /** 266 * @brief Create a common event publish information. 267 * 268 * @param ordered Indicates whether the common event is ordered. 269 * @return Returns the CommonEvent_PublishInfo, if create failed, returns null. 270 * @since 18 271 */ 272 CommonEvent_PublishInfo* OH_CommonEvent_CreatePublishInfo(bool ordered); 273 274 /** 275 * @brief Destroy the common event publish information. 276 * 277 * @param info Indicates the publish information. 278 * @since 18 279 */ 280 void OH_CommonEvent_DestroyPublishInfo(CommonEvent_PublishInfo* info); 281 282 /** 283 * @brief Set the bundleName of publish information. 284 * 285 * @param info Indicates the publish information. 286 * @param bundleName Indicates the bundleName. 287 * @return Returns the error code. 288 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 289 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 290 * @since 18 291 */ 292 CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoBundleName(CommonEvent_PublishInfo* info, const char* bundleName); 293 294 /** 295 * @brief Set the permissions of publish information. 296 * 297 * @param info Indicates the publish information. 298 * @param permissions Indicates the array of permissions. 299 * @param num Indicates the count of permissions. 300 * @return Returns the error code. 301 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 302 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 303 * @since 18 304 */ 305 CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoPermissions(CommonEvent_PublishInfo* info, 306 const char* permissions[], int32_t num); 307 308 /** 309 * @brief Set the code of publish information. 310 * 311 * @param info Indicates the publish information. 312 * @param code Indicates the code. 313 * @return Returns the error code. 314 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 315 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 316 * @since 18 317 */ 318 CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoCode(CommonEvent_PublishInfo* info, int32_t code); 319 320 /** 321 * @brief Set the data of publish information. 322 * 323 * @param info Indicates the publish information. 324 * @param data Indicates the data. 325 * @param length Indicates the length of data. 326 * @return Returns the error code. 327 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 328 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 329 * @since 18 330 */ 331 CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoData(CommonEvent_PublishInfo* info, 332 const char* data, size_t length); 333 334 /** 335 * @brief Set the parameters of publish information. 336 * 337 * @param info Indicates the publish information. 338 * @param param Indicates the parameters. 339 * @return Returns the error code. 340 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 341 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 342 * @since 18 343 */ 344 CommonEvent_ErrCode OH_CommonEvent_SetPublishInfoParameters(CommonEvent_PublishInfo* info, 345 CommonEvent_Parameters* param); 346 347 /** 348 * @brief Create a common event publish information. 349 * 350 * @return Returns the CommonEvent_PublishInfo, if create failed, returns null. 351 * @since 18 352 */ 353 CommonEvent_Parameters* OH_CommonEvent_CreateParameters(); 354 355 /** 356 * @brief Destroy the common event publish information. 357 * 358 * @param param Indicates the publish information. 359 * @since 18 360 */ 361 void OH_CommonEvent_DestroyParameters(CommonEvent_Parameters* param); 362 363 /** 364 * @brief Check whether the parameters data contains a key. 365 * 366 * @param para Indicates the parameters data. 367 * @param key Indicates the key. 368 * @return Returns the result of check, true means it contains. 369 * @since 12 370 */ 371 bool OH_CommonEvent_HasKeyInParameters(const CommonEvent_Parameters* para, const char* key); 372 373 /** 374 * @brief Get int data from parameters data by key. 375 * 376 * @param para Indicates the parameters data. 377 * @param key Indicates the key. 378 * @param defaultValue Indicates default return value. 379 * @return Returns the int data of the key in the parameters. 380 * @since 12 381 */ 382 int OH_CommonEvent_GetIntFromParameters(const CommonEvent_Parameters* para, const char* key, const int defaultValue); 383 384 /** 385 * @brief Set int data to parameters data by key. 386 * 387 * @param param Indicates the parameters data. 388 * @param key Indicates the key. 389 * @param value Indicates the int data. 390 * @return Returns the error code. 391 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 392 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 393 * @since 18 394 */ 395 CommonEvent_ErrCode OH_CommonEvent_SetIntToParameters(CommonEvent_Parameters* param, const char* key, int value); 396 397 /** 398 * @brief Get int array data from parameters data by key. 399 * 400 * @param para Indicates the parameters data. 401 * @param key Indicates the key. 402 * @param array Indicates the int array. 403 * @return Returns the length of the array. 404 * @since 12 405 */ 406 int32_t OH_CommonEvent_GetIntArrayFromParameters(const CommonEvent_Parameters* para, const char* key, int** array); 407 408 /** 409 * @brief Set int array data to parameters data by key. 410 * 411 * @param param Indicates the parameters data. 412 * @param key Indicates the key. 413 * @param value Indicates the int array data. 414 * @param num Indicates the length of the array. 415 * @return Returns the error code. 416 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 417 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 418 * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED} if a memory allocation error occurs. 419 * @since 18 420 */ 421 CommonEvent_ErrCode OH_CommonEvent_SetIntArrayToParameters(CommonEvent_Parameters* param, const char* key, 422 const int* value, size_t num); 423 424 /** 425 * @brief Get long data from parameters data by key. 426 * 427 * @param para Indicates the parameters data. 428 * @param key Indicates the key. 429 * @param defaultValue Indicates default return value. 430 * @return Returns the long data of the key in the parameters. 431 * @since 12 432 */ 433 long OH_CommonEvent_GetLongFromParameters(const CommonEvent_Parameters* para, const char* key, const long defaultValue); 434 435 /** 436 * @brief Set long data to parameters data by key. 437 * 438 * @param param Indicates the parameters data. 439 * @param key Indicates the key. 440 * @param value Indicates the long data. 441 * @return Returns the error code. 442 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 443 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 444 * @since 18 445 */ 446 CommonEvent_ErrCode OH_CommonEvent_SetLongToParameters(CommonEvent_Parameters* param, const char* key, long value); 447 448 /** 449 * @brief Get long array data from parameters data by key. 450 * 451 * @param para Indicates the parameters data. 452 * @param key Indicates the key. 453 * @param array Indicates the long array. 454 * @return Returns the length of the array. 455 * @since 12 456 */ 457 int32_t OH_CommonEvent_GetLongArrayFromParameters(const CommonEvent_Parameters* para, const char* key, long** array); 458 459 /** 460 * @brief Set long array data to parameters data by key. 461 * 462 * @param param Indicates the parameters data. 463 * @param key Indicates the key. 464 * @param value Indicates the long array data. 465 * @param num Indicates the length of the array. 466 * @return Returns the error code. 467 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 468 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 469 * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED} if a memory allocation error occurs. 470 * @since 18 471 */ 472 CommonEvent_ErrCode OH_CommonEvent_SetLongArrayToParameters(CommonEvent_Parameters* param, const char* key, 473 const long* value, size_t num); 474 475 /** 476 * @brief Get bool data from parameters data by key. 477 * 478 * @param para Indicates the parameters data. 479 * @param key Indicates the key. 480 * @param defaultValue Indicates default return value. 481 * @return Returns the bool data of the key in the parameters. 482 * @since 12 483 */ 484 bool OH_CommonEvent_GetBoolFromParameters(const CommonEvent_Parameters* para, const char* key, const bool defaultValue); 485 486 /** 487 * @brief Set bool data to parameters data by key. 488 * 489 * @param param Indicates the parameters data. 490 * @param key Indicates the key. 491 * @param value Indicates the bool data. 492 * @return Returns the error code. 493 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 494 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 495 * @since 18 496 */ 497 CommonEvent_ErrCode OH_CommonEvent_SetBoolToParameters(CommonEvent_Parameters* param, const char* key, bool value); 498 499 /** 500 * @brief Get bool array data from parameters data by key. 501 * 502 * @param para Indicates the parameters data. 503 * @param key Indicates the key. 504 * @param array Indicates the bool array. 505 * @return Returns the length of the array. 506 * @since 12 507 */ 508 int32_t OH_CommonEvent_GetBoolArrayFromParameters(const CommonEvent_Parameters* para, const char* key, bool** array); 509 510 /** 511 * @brief Set bool array data to parameters data by key. 512 * 513 * @param param Indicates the parameters data. 514 * @param key Indicates the key. 515 * @param value Indicates the bool array data. 516 * @param num Indicates the length of the array. 517 * @return Returns the error code. 518 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 519 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 520 * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED} if a memory allocation error occurs. 521 * @since 18 522 */ 523 CommonEvent_ErrCode OH_CommonEvent_SetBoolArrayToParameters(CommonEvent_Parameters* param, const char* key, 524 const bool* value, size_t num); 525 526 /** 527 * @brief Get char data from parameters data by key. 528 * 529 * @param para Indicates the parameters data. 530 * @param key Indicates the key. 531 * @param defaultValue Indicates default return value. 532 * @return Returns the char data of the key in the parameters. 533 * @since 12 534 */ 535 char OH_CommonEvent_GetCharFromParameters(const CommonEvent_Parameters* para, const char* key, const char defaultValue); 536 537 /** 538 * @brief Set char data to parameters data by key. 539 * 540 * @param param Indicates the parameters data. 541 * @param key Indicates the key. 542 * @param value Indicates the char data. 543 * @return Returns the error code. 544 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 545 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 546 * @since 18 547 */ 548 CommonEvent_ErrCode OH_CommonEvent_SetCharToParameters(CommonEvent_Parameters* param, const char* key, char value); 549 550 /** 551 * @brief Get char array data from parameters data by key. 552 * 553 * @param para Indicates the parameters data. 554 * @param key Indicates the key. 555 * @param array Indicates the char array. 556 * @return Returns the length of the array. 557 * @since 12 558 */ 559 int32_t OH_CommonEvent_GetCharArrayFromParameters(const CommonEvent_Parameters* para, const char* key, char** array); 560 561 /** 562 * @brief Set char array data to parameters data by key. 563 * 564 * @param param Indicates the parameters data. 565 * @param key Indicates the key. 566 * @param value Indicates the char array data. 567 * @param num Indicates the length of the array. 568 * @return Returns the error code. 569 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 570 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 571 * @since 18 572 */ 573 CommonEvent_ErrCode OH_CommonEvent_SetCharArrayToParameters(CommonEvent_Parameters* param, const char* key, 574 const char* value, size_t num); 575 576 /** 577 * @brief Get double data from parameters data by key. 578 * 579 * @param para Indicates the parameters data. 580 * @param key Indicates the key. 581 * @param defaultValue Indicates default return value. 582 * @return Returns the double data of the key in the parameters. 583 * @since 12 584 */ 585 double OH_CommonEvent_GetDoubleFromParameters(const CommonEvent_Parameters* para, const char* key, 586 const double defaultValue); 587 588 /** 589 * @brief Set double data to parameters data by key. 590 * 591 * @param param Indicates the parameters data. 592 * @param key Indicates the key. 593 * @param value Indicates the double data. 594 * @return Returns the error code. 595 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 596 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 597 * @since 18 598 */ 599 CommonEvent_ErrCode OH_CommonEvent_SetDoubleToParameters(CommonEvent_Parameters* param, const char* key, 600 double value); 601 602 /** 603 * @brief Get double array data from parameters data by key. 604 * 605 * @param para Indicates the parameters data. 606 * @param key Indicates the key. 607 * @param array Indicates the double array. 608 * @return Returns the length of the array, default is 0. 609 * @since 12 610 */ 611 int32_t OH_CommonEvent_GetDoubleArrayFromParameters(const CommonEvent_Parameters* para, const char* key, 612 double** array); 613 614 /** 615 * @brief Set double array data to parameters data by key. 616 * 617 * @param param Indicates the parameters data. 618 * @param key Indicates the key. 619 * @param value Indicates the double array data. 620 * @param num Indicates the length of the array. 621 * @return Returns the error code. 622 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 623 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 624 * Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED} if a memory allocation error occurs. 625 * @since 18 626 */ 627 CommonEvent_ErrCode OH_CommonEvent_SetDoubleArrayToParameters(CommonEvent_Parameters* param, const char* key, 628 const double* value, size_t num); 629 630 /** 631 * @brief Publish a commen event. 632 * 633 * @param event Indicates the name of the common event. 634 * @return Returns the error code. 635 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 636 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 637 * Returns {@link COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED} if the common event sending frequency too high, 638 * add since api 20. 639 * Returns {@link COMMONEVENT_ERR_FAIL_SEND_REQUEST } if IPC request failed to send. 640 * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. 641 * @since 18 642 */ 643 CommonEvent_ErrCode OH_CommonEvent_Publish(const char* event); 644 645 /** 646 * @brief Publish a commen event with specified publish information. 647 * 648 * @param event Indicates the name of the common event. 649 * @param info Indicates the publish information. 650 * @return Returns the error code. 651 * Returns {@link COMMONEVENT_ERR_OK} if the operation is successful. 652 * Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs. 653 * Returns {@link COMMONEVENT_ERR_SENDING_LIMIT_EXCEEDED} if the common event sending frequency too high, 654 * add since api 20. 655 * Returns {@link COMMONEVENT_ERR_FAIL_SEND_REQUEST } if IPC request failed to send. 656 * Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done. 657 * @since 18 658 */ 659 CommonEvent_ErrCode OH_CommonEvent_PublishWithInfo(const char* event, const CommonEvent_PublishInfo* info); 660 661 /** 662 * @brief Check an event by a subscriber whether it is ordered. 663 * 664 * @param subscriber Indicates the subscriber. 665 * @return Returns the result of check, true means ordered. 666 * @since 18 667 */ 668 bool OH_CommonEvent_IsOrderedCommonEvent(const CommonEvent_Subscriber* subscriber); 669 670 /** 671 * @brief Finish an ordered event by a subscriber. 672 * 673 * @param subscriber Indicates the subscriber. 674 * @return Returns the result of operation, true means succeeded. 675 * @since 18 676 */ 677 bool OH_CommonEvent_FinishCommonEvent(CommonEvent_Subscriber* subscriber); 678 679 /** 680 * @brief Check an event by a subscriber whether it is aborted. 681 * 682 * @param subscriber Indicates the subscriber. 683 * @return Returns the result of check, true means aborted. 684 * @since 18 685 */ 686 bool OH_CommonEvent_GetAbortCommonEvent(const CommonEvent_Subscriber* subscriber); 687 688 /** 689 * @brief Abort an ordered event by a subscriber. 690 * 691 * @param subscriber Indicates the subscriber. 692 * @return Returns the result of operation, true means succeeded. 693 * @since 18 694 */ 695 bool OH_CommonEvent_AbortCommonEvent(CommonEvent_Subscriber* subscriber); 696 697 /** 698 * @brief Clear the aborted flag of an ordered event by a subscriber. 699 * 700 * @param subscriber Indicates the subscriber. 701 * @return Returns the result of operation, true means succeeded. 702 * @since 18 703 */ 704 bool OH_CommonEvent_ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber); 705 706 /** 707 * @brief Get code from an ordered event by a subscriber. 708 * 709 * @param subscriber Indicates the subscriber. 710 * @return Returns the code, default is 0. 711 * @since 18 712 */ 713 int32_t OH_CommonEvent_GetCodeFromSubscriber(const CommonEvent_Subscriber* subscriber); 714 715 /** 716 * @brief Set code to an ordered event by a subscriber. 717 * 718 * @param subscriber Indicates the subscriber. 719 * @param code Indicates the code. 720 * @return Returns the result of operation, true means succeeded. 721 * @since 18 722 */ 723 bool OH_CommonEvent_SetCodeToSubscriber(CommonEvent_Subscriber* subscriber, int32_t code); 724 725 /** 726 * @brief Get data from an ordered event by a subscriber. 727 * 728 * @param subscriber Indicates the subscriber. 729 * @return Returns the data, default is null. 730 * @since 18 731 */ 732 const char* OH_CommonEvent_GetDataFromSubscriber(const CommonEvent_Subscriber* subscriber); 733 734 /** 735 * @brief Set data to an ordered event by a subscriber. 736 * 737 * @param subscriber Indicates the subscriber. 738 * @param data Indicates the data. 739 * @param length Indicates the length of data. 740 * @return Returns the result of operation, true means succeeded. 741 * @since 18 742 */ 743 bool OH_CommonEvent_SetDataToSubscriber(CommonEvent_Subscriber* subscriber, const char* data, size_t length); 744 745 #ifdef __cplusplus 746 } 747 #endif 748 #endif // OH_COMMONEVENT_H 749 /** @} */ 750