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