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