1/* 2 * Copyright (c) 2022 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 * @file 18 * @kit BackgroundTasksKit 19 */ 20 21import { AsyncCallback } from './@ohos.base'; 22import notification from './@ohos.notificationManager'; 23import { NotificationSlot } from './notification/notificationSlot'; 24import { ValuesBucket } from './@ohos.data.ValuesBucket'; 25 26/** 27 * Providers static methods for managing reminders, including publishing or canceling a reminder. 28 * Add or remove a notification slot, and obtain or cancel all reminders of the current application. 29 * 30 * @namespace reminderAgentManager 31 * @syscap SystemCapability.Notification.ReminderAgent 32 * @since 9 33 */ 34declare namespace reminderAgentManager { 35 /** 36 * Publishes a scheduled reminder. 37 * 38 * @permission ohos.permission.PUBLISH_AGENT_REMINDER 39 * @param { ReminderRequest } reminderReq - Indicates the reminder instance to publish. 40 * @param { AsyncCallback<number> } callback - Indicates the callback function. 41 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 42 * @throws { BusinessError } 1700001 - Notification is not enabled. 43 * @throws { BusinessError } 1700002 - The number of reminders exceeds the limit. 44 * @syscap SystemCapability.Notification.ReminderAgent 45 * @since 9 46 */ 47 function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void; 48 49 /** 50 * Publishes a scheduled reminder. 51 * 52 * @permission ohos.permission.PUBLISH_AGENT_REMINDER 53 * @param { ReminderRequest } reminderReq - Indicates the reminder instance to publish. 54 * @returns { Promise<number> } The reminder id. 55 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 56 * @throws { BusinessError } 1700001 - Notification is not enabled. 57 * @throws { BusinessError } 1700002 - The number of reminders exceeds the limit. 58 * @syscap SystemCapability.Notification.ReminderAgent 59 * @since 9 60 */ 61 function publishReminder(reminderReq: ReminderRequest): Promise<number>; 62 63 /** 64 * Cancel a reminder. 65 * 66 * @param { number } reminderId - Indicates the reminder id. 67 * @param { AsyncCallback<void> } callback - Indicates the callback function. 68 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 69 * @throws { BusinessError } 1700003 - The reminder does not exist. 70 * @throws { BusinessError } 1700004 - The bundle name does not exist. 71 * @syscap SystemCapability.Notification.ReminderAgent 72 * @since 9 73 */ 74 function cancelReminder(reminderId: number, callback: AsyncCallback<void>): void; 75 76 /** 77 * Cancel a reminder. 78 * 79 * @param { number } reminderId - Indicates the reminder id. 80 * @returns { Promise<void> } The promise returned by the function. 81 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 82 * @throws { BusinessError } 1700003 - The reminder does not exist. 83 * @throws { BusinessError } 1700004 - The bundle name does not exist. 84 * @syscap SystemCapability.Notification.ReminderAgent 85 * @since 9 86 */ 87 function cancelReminder(reminderId: number): Promise<void>; 88 89 /** 90 * Obtains all the valid reminders of current application. 91 * 92 * @param { AsyncCallback<Array<ReminderRequest>> } callback - Indicates the callback function. 93 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 94 * @throws { BusinessError } 1700004 - The bundle name does not exist. 95 * @syscap SystemCapability.Notification.ReminderAgent 96 * @since 9 97 */ 98 function getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void; 99 100 /** 101 * Obtains all the valid reminders of current application. 102 * 103 * @returns { Promise<Array<ReminderRequest>> } The promise returned by the function. 104 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 105 * @throws { BusinessError } 1700004 - The bundle name does not exist. 106 * @syscap SystemCapability.Notification.ReminderAgent 107 * @since 9 108 */ 109 function getValidReminders(): Promise<Array<ReminderRequest>>; 110 111 /** 112 * Cancel all the reminders of current application. 113 * 114 * @param { AsyncCallback<void> } callback - Indicates the callback function. 115 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 116 * @throws { BusinessError } 1700004 - The bundle name does not exist. 117 * @syscap SystemCapability.Notification.ReminderAgent 118 * @since 9 119 */ 120 function cancelAllReminders(callback: AsyncCallback<void>): void; 121 122 /** 123 * Cancel all the reminders of current application. 124 * 125 * @returns { Promise<void> } The promise returned by the function. 126 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 127 * @throws { BusinessError } 1700004 - The bundle name does not exist. 128 * @syscap SystemCapability.Notification.ReminderAgent 129 * @since 9 130 */ 131 function cancelAllReminders(): Promise<void>; 132 133 /** 134 * Add notification slot. 135 * 136 * @param { NotificationSlot } slot - Indicates the slot. 137 * @param { AsyncCallback<void> } callback - Indicates the callback function. 138 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 139 * @syscap SystemCapability.Notification.ReminderAgent 140 * @since 9 141 */ 142 function addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void; 143 144 /** 145 * Add notification slot. 146 * 147 * @param { NotificationSlot } slot - Indicates the slot. 148 * @returns { Promise<void> } The promise returned by the function. 149 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 150 * @syscap SystemCapability.Notification.ReminderAgent 151 * @since 9 152 */ 153 function addNotificationSlot(slot: NotificationSlot): Promise<void>; 154 155 /** 156 * Deletes a created notification slot based on the slot type. 157 * 158 * @param { notification.SlotType } slotType Indicates the type of the slot. 159 * @param { AsyncCallback<void> } callback - Indicates the callback function. 160 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 161 * @syscap SystemCapability.Notification.ReminderAgent 162 * @since 9 163 */ 164 function removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void; 165 166 /** 167 * Deletes a created notification slot based on the slot type. 168 * 169 * @param { notification.SlotType } slotType Indicates the type of the slot. 170 * @returns { Promise<void> } The promise returned by the function. 171 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 172 * @syscap SystemCapability.Notification.ReminderAgent 173 * @since 9 174 */ 175 function removeNotificationSlot(slotType: notification.SlotType): Promise<void>; 176 177 /** 178 * add exclude date for calendar reminder request. 179 * 180 * @param { number } reminderId reminder id 181 * @param { Date } date date time 182 * @returns { Promise<void> } The promise returned by the function. 183 * @throws { BusinessError } 201 - Permission denied 184 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 185 * @throws { BusinessError } 1700003 - The reminder does not exist. 186 * @syscap SystemCapability.Notification.ReminderAgent 187 * @since 12 188 */ 189 function addExcludeDate(reminderId: number, date: Date): Promise<void>; 190 191 /** 192 * delete exclude date for calendar reminder request. 193 * 194 * @param { number } reminderId reminder id 195 * @returns { Promise<void> } The promise returned by the function. 196 * @throws { BusinessError } 201 - Permission denied 197 * @throws { BusinessError } 1700003 - The reminder does not exist. 198 * @syscap SystemCapability.Notification.ReminderAgent 199 * @since 12 200 */ 201 function deleteExcludeDates(reminderId: number): Promise<void>; 202 203 /** 204 * get exclude dates 205 * 206 * @param { number } reminderId reminder id 207 * @returns { Promise<Array<Date>> } The promise returned by the function. 208 * @throws { BusinessError } 201 - Permission denied 209 * @throws { BusinessError } 1700003 - The reminder does not exist. 210 * @syscap SystemCapability.Notification.ReminderAgent 211 * @since 12 212 */ 213 function getExcludeDates(reminderId: number): Promise<Array<Date>>; 214 215 /** 216 * Obtains all the valid reminders of current application, include reminderId. 217 * 218 * @returns { Promise<Array<ReminderInfo>> } The promise returned by the function. 219 * @throws { BusinessError } 201 - Permission denied. 220 * @syscap SystemCapability.Notification.ReminderAgent 221 * @since 12 222 */ 223 function getAllValidReminders(): Promise<Array<ReminderInfo>>; 224 225 /** 226 * Declares action button type. 227 * 228 * @enum { number } 229 * @syscap SystemCapability.Notification.ReminderAgent 230 * @since 9 231 */ 232 export enum ActionButtonType { 233 /** 234 * Button for closing the reminder. 235 * 236 * @syscap SystemCapability.Notification.ReminderAgent 237 * @since 9 238 */ 239 ACTION_BUTTON_TYPE_CLOSE = 0, 240 241 /** 242 * Button for snoozing the reminder. 243 * 244 * @syscap SystemCapability.Notification.ReminderAgent 245 * @since 9 246 */ 247 ACTION_BUTTON_TYPE_SNOOZE = 1, 248 249 /** 250 * The custom button. 251 * 252 * @syscap SystemCapability.Notification.ReminderAgent 253 * @systemapi Hide this for inner system use. 254 * @since 10 255 */ 256 ACTION_BUTTON_TYPE_CUSTOM = 2 257 } 258 259 /** 260 * Declares reminder type. 261 * 262 * @enum { number } 263 * 264 * @syscap SystemCapability.Notification.ReminderAgent 265 * @since 9 266 */ 267 export enum ReminderType { 268 /** 269 * Countdown reminder. 270 * 271 * @syscap SystemCapability.Notification.ReminderAgent 272 * @since 9 273 */ 274 REMINDER_TYPE_TIMER = 0, 275 276 /** 277 * Calendar reminder. 278 * 279 * @syscap SystemCapability.Notification.ReminderAgent 280 * @since 9 281 */ 282 REMINDER_TYPE_CALENDAR = 1, 283 284 /** 285 * Alarm reminder. 286 * 287 * @syscap SystemCapability.Notification.ReminderAgent 288 * @since 9 289 */ 290 REMINDER_TYPE_ALARM = 2 291 } 292 293 /** 294 * Action button information. The button will show on displayed reminder. 295 * 296 * @interface ActionButton 297 * 298 * @syscap SystemCapability.Notification.ReminderAgent 299 * @since 9 300 */ 301 interface ActionButton { 302 /** 303 * Text on the button. 304 * 305 * @syscap SystemCapability.Notification.ReminderAgent 306 * @since 9 307 */ 308 title: string; 309 310 /** 311 * Resource ID for button title. 312 * 313 * @type { ?string } 314 * @syscap SystemCapability.Notification.ReminderAgent 315 * @since 11 316 */ 317 titleResource?: string; 318 319 /** 320 * Button type. 321 * 322 * @syscap SystemCapability.Notification.ReminderAgent 323 * @since 9 324 */ 325 type: ActionButtonType; 326 327 /** 328 * Information about the ability that is redirected to when the button is clicked. 329 * 330 * @syscap SystemCapability.Notification.ReminderAgent 331 * @systemapi Hide this for inner system use. 332 * @since 10 333 */ 334 wantAgent?: WantAgent; 335 336 /** 337 * It will update the database when the button is clicked. 338 * 339 * @type { ?DataShareUpdate } 340 * @syscap SystemCapability.Notification.ReminderAgent 341 * @systemapi Hide this for inner system use. 342 * @since 11 343 */ 344 dataShareUpdate?: DataShareUpdate; 345 } 346 347 /** 348 * Want agent information. 349 * It will switch to target ability when you click the displayed reminder. 350 * 351 * @interface WantAgent 352 * @syscap SystemCapability.Notification.ReminderAgent 353 * @since 9 354 */ 355 interface WantAgent { 356 /** 357 * Name of the package redirected to when the reminder notification is clicked. 358 * 359 * @syscap SystemCapability.Notification.ReminderAgent 360 * @since 9 361 */ 362 pkgName: string; 363 364 /** 365 * Name of the ability that is redirected to when the reminder notification is clicked. 366 * 367 * @syscap SystemCapability.Notification.ReminderAgent 368 * @since 9 369 */ 370 abilityName: string; 371 372 /** 373 * The Uniform Resource Identifier (URI) that will be redirected to. 374 * 375 * @syscap SystemCapability.Notification.ReminderAgent 376 * @since 12 377 */ 378 uri?: string; 379 380 /** 381 * The description of the WantParams object in an Want 382 * 383 * @syscap SystemCapability.Notification.ReminderAgent 384 * @since 12 385 */ 386 parameters?: Record<string, Object>; 387 } 388 389 /** 390 * DataShareUpdate information. 391 * It will update the database when the button is clicked. 392 * 393 * @interface DataShareUpdate 394 * @syscap SystemCapability.Notification.ReminderAgent 395 * @systemapi Hide this for inner system use. 396 * @since 11 397 */ 398 interface DataShareUpdate { 399 /** 400 * Indicates the path of data to update. 401 * 402 * @type { string } 403 * @syscap SystemCapability.Notification.ReminderAgent 404 * @systemapi Hide this for inner system use. 405 * @since 11 406 */ 407 uri: string; 408 409 /** 410 * Indicates filter criteria. 411 * 412 * @type { Record<string, number | string | boolean> } 413 * @syscap SystemCapability.Notification.ReminderAgent 414 * @systemapi Hide this for inner system use. 415 * @since 11 416 */ 417 equalTo: Record<string, number | string | boolean>; 418 419 /** 420 * Indicates the data to update. This parameter can be null. 421 * 422 * @type { ValuesBucket } 423 * @syscap SystemCapability.Notification.ReminderAgent 424 * @systemapi Hide this for inner system use. 425 * @since 11 426 */ 427 value: ValuesBucket; 428 } 429 430 /** 431 * Max screen want agent information. 432 * 433 * @interface MaxScreenWantAgent 434 * @syscap SystemCapability.Notification.ReminderAgent 435 * @since 9 436 */ 437 interface MaxScreenWantAgent { 438 /** 439 * Name of the package that is automatically started when the reminder arrives and the device is not in use. 440 * 441 * @syscap SystemCapability.Notification.ReminderAgent 442 * @since 9 443 */ 444 pkgName: string; 445 446 /** 447 * Name of the ability that is automatically started when the reminder arrives and the device is not in use. 448 * 449 * @syscap SystemCapability.Notification.ReminderAgent 450 * @since 9 451 */ 452 abilityName: string; 453 } 454 455 /** 456 * Reminder Common information. 457 * 458 * @interface ReminderRequest 459 * @syscap SystemCapability.Notification.ReminderAgent 460 * @since 9 461 */ 462 interface ReminderRequest { 463 /** 464 * Type of the reminder. 465 * 466 * @syscap SystemCapability.Notification.ReminderAgent 467 * @since 9 468 */ 469 reminderType: ReminderType; 470 471 /** 472 * Action button displayed on the reminder notification. 473 * (The parameter is optional. Up to two buttons are supported). 474 * 475 * @syscap SystemCapability.Notification.ReminderAgent 476 * @since 9 477 */ 478 /** 479 * Action button displayed on the reminder notification. 480 * (The parameter is optional. Up to three buttons are supported). 481 * 482 * @syscap SystemCapability.Notification.ReminderAgent 483 * @since 10 484 */ 485 actionButton?: [ActionButton?, ActionButton?, ActionButton?]; 486 487 /** 488 * Information about the ability that is redirected to when the notification is clicked. 489 * 490 * @syscap SystemCapability.Notification.ReminderAgent 491 * @since 9 492 */ 493 wantAgent?: WantAgent; 494 495 /** 496 * Information about the ability that is automatically started when the reminder arrives. 497 * If the device is in use, a notification will be displayed. 498 * 499 * @syscap SystemCapability.Notification.ReminderAgent 500 * @since 9 501 */ 502 maxScreenWantAgent?: MaxScreenWantAgent; 503 504 /** 505 * Ringing duration. 506 * 507 * @syscap SystemCapability.Notification.ReminderAgent 508 * @since 9 509 */ 510 ringDuration?: number; 511 512 /** 513 * Number of reminder snooze times. 514 * 515 * @syscap SystemCapability.Notification.ReminderAgent 516 * @since 9 517 */ 518 snoozeTimes?: number; 519 520 /** 521 * Reminder snooze interval. 522 * 523 * @syscap SystemCapability.Notification.ReminderAgent 524 * @since 9 525 */ 526 timeInterval?: number; 527 528 /** 529 * Reminder title. 530 * 531 * @syscap SystemCapability.Notification.ReminderAgent 532 * @since 9 533 */ 534 title?: string; 535 536 /** 537 * Reminder content. 538 * 539 * @syscap SystemCapability.Notification.ReminderAgent 540 * @since 9 541 */ 542 content?: string; 543 544 /** 545 * Content to be displayed when the reminder is expired. 546 * 547 * @syscap SystemCapability.Notification.ReminderAgent 548 * @since 9 549 */ 550 expiredContent?: string; 551 552 /** 553 * Content to be displayed when the reminder is snoozing. 554 * 555 * @syscap SystemCapability.Notification.ReminderAgent 556 * @since 9 557 */ 558 snoozeContent?: string; 559 560 /** 561 * Notification id. If there are reminders with the same ID, the later one will overwrite the earlier one. 562 * 563 * @syscap SystemCapability.Notification.ReminderAgent 564 * @since 9 565 */ 566 notificationId?: number; 567 568 /** 569 * If the same group ID is set for reminders, these reminders are canceled together. 570 * 571 * @type { ?string } 572 * @syscap SystemCapability.Notification.ReminderAgent 573 * @since 11 574 */ 575 groupId?: string; 576 577 /** 578 * Type of the slot used by the reminder. 579 * 580 * @syscap SystemCapability.Notification.ReminderAgent 581 * @since 9 582 */ 583 slotType?: notification.SlotType; 584 585 /** 586 * Whether the notification is automatically cleared. 587 * 588 * @syscap SystemCapability.Notification.ReminderAgent 589 * @since 10 590 */ 591 tapDismissed?: boolean; 592 593 /** 594 * Time when the notification is automatically cleared. 595 * 596 * @syscap SystemCapability.Notification.ReminderAgent 597 * @since 10 598 */ 599 autoDeletedTime?: number; 600 601 /** 602 * Type of the snoozeSlot used by the reminder. 603 * 604 * @type { ?notification.SlotType } 605 * @syscap SystemCapability.Notification.ReminderAgent 606 * @since 11 607 */ 608 snoozeSlotType?: notification.SlotType; 609 610 /** 611 * The directory of storing reminder announcements. 612 * 613 * @type { ?string } 614 * @syscap SystemCapability.Notification.ReminderAgent 615 * @since 11 616 */ 617 customRingUri?: string; 618 } 619 620 /** 621 * Calendar reminder information. 622 * 623 * @interface ReminderRequestCalendar 624 * @syscap SystemCapability.Notification.ReminderAgent 625 * @since 9 626 */ 627 interface ReminderRequestCalendar extends ReminderRequest { 628 /** 629 * Reminder time. 630 * 631 * @syscap SystemCapability.Notification.ReminderAgent 632 * @since 9 633 */ 634 dateTime: LocalDateTime; 635 636 /** 637 * Month in which the reminder repeats. 638 * 639 * @syscap SystemCapability.Notification.ReminderAgent 640 * @since 9 641 */ 642 repeatMonths?: Array<number>; 643 644 /** 645 * Date on which the reminder repeats. 646 * 647 * @syscap SystemCapability.Notification.ReminderAgent 648 * @since 9 649 */ 650 repeatDays?: Array<number>; 651 652 /** 653 * Days of a week when the reminder repeats. 654 * 655 * @type { ?Array<number> } 656 * @syscap SystemCapability.Notification.ReminderAgent 657 * @since 11 658 */ 659 daysOfWeek?: Array<number>; 660 661 /** 662 * calendar end date time 663 * 664 * @syscap SystemCapability.Notification.ReminderAgent 665 * @since 12 666 */ 667 endDateTime?: LocalDateTime; 668 669 /** 670 * For custom repeat calendar(RRule), the service extension will pull up when 671 * param set and the notification arrived. 672 * 673 * @syscap SystemCapability.Notification.ReminderAgent 674 * @systemapi Hide this for inner system use. 675 * @since 12 676 */ 677 rruleWantAgent?: WantAgent; 678 } 679 680 /** 681 * Alarm reminder information. 682 * 683 * @interface ReminderRequestAlarm 684 * @syscap SystemCapability.Notification.ReminderAgent 685 * @since 9 686 */ 687 interface ReminderRequestAlarm extends ReminderRequest { 688 /** 689 * Hour portion of the reminder time. 690 * 691 * @syscap SystemCapability.Notification.ReminderAgent 692 * @since 9 693 */ 694 hour: number; 695 696 /** 697 * Minute portion of the reminder time. 698 * 699 * @syscap SystemCapability.Notification.ReminderAgent 700 * @since 9 701 */ 702 minute: number; 703 704 /** 705 * Days of a week when the reminder repeats. 706 * 707 * @syscap SystemCapability.Notification.ReminderAgent 708 * @since 9 709 */ 710 daysOfWeek?: Array<number>; 711 } 712 713 /** 714 * CountDown reminder information. 715 * 716 * @interface ReminderRequestTimer 717 * 718 * @syscap SystemCapability.Notification.ReminderAgent 719 * @since 9 720 */ 721 interface ReminderRequestTimer extends ReminderRequest { 722 /** 723 * The number of seconds to count down. 724 * 725 * @syscap SystemCapability.Notification.ReminderAgent 726 * @since 9 727 */ 728 triggerTimeInSeconds: number; 729 } 730 731 /** 732 * Reminder information, include reminderId. 733 * 734 * @interface ReminderInfo 735 * @syscap SystemCapability.Notification.ReminderAgent 736 * @since 12 737 */ 738 interface ReminderInfo { 739 reminderId: number; 740 741 reminderReq: ReminderRequest; 742 } 743 744 /** 745 * Used for ReminderRequestCalendar when set the time. 746 * 747 * @interface LocalDateTime 748 * @syscap SystemCapability.Notification.ReminderAgent 749 * @since 9 750 */ 751 interface LocalDateTime { 752 /** 753 * Value of year. 754 * 755 * @syscap SystemCapability.Notification.ReminderAgent 756 * @since 9 757 */ 758 year: number; 759 760 /** 761 * Value of month. 762 * 763 * @syscap SystemCapability.Notification.ReminderAgent 764 * @since 9 765 */ 766 month: number; 767 768 /** 769 * Value of day. 770 * 771 * @syscap SystemCapability.Notification.ReminderAgent 772 * @since 9 773 */ 774 day: number; 775 776 /** 777 * Value of hour. 778 * 779 * @syscap SystemCapability.Notification.ReminderAgent 780 * @since 9 781 */ 782 hour: number; 783 784 /** 785 * Value of minute. 786 * 787 * @syscap SystemCapability.Notification.ReminderAgent 788 * @since 9 789 */ 790 minute: number; 791 792 /** 793 * Value of second. 794 * 795 * @syscap SystemCapability.Notification.ReminderAgent 796 * @since 9 797 */ 798 second?: number; 799 } 800} 801export default reminderAgentManager; 802