1# @ohos.multimedia.systemSoundManager (System Sound Management) (System API) 2 3The systemSoundManager module provides basic capabilities for managing system sounds, including setting and obtaining ringtones and obtaining a player to play the ringtones. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - The APIs provided by this module are system APIs. 9 10## Modules to Import 11 12```ts 13import { systemSoundManager } from '@kit.AudioKit'; 14``` 15 16## Constants 17 18**System API**: This is a system API. 19 20**System capability**: SystemCapability.Multimedia.SystemSound.Core 21 22| Name | Type| Value | Description | 23|------------------------------------------|---|-----|---------| 24| TONE_CATEGORY_RINGTONE<sup>12+</sup> | number | 1 | Ringtone. | 25| TONE_CATEGORY_TEXT_MESSAGE<sup>12+</sup> | number | 2 | SMS tone.| 26| TONE_CATEGORY_NOTIFICATION<sup>12+</sup> | number | 4 | Notification tone.| 27| TONE_CATEGORY_ALARM<sup>12+</sup> | number | 8 | Alarm tone.| 28| TONE_CATEGORY_CONTACTS<sup>20+</sup> | number | 16 | Contacts tone.| 29 30## RingtoneType 31 32Enumerates the ringtone types. 33 34**System API**: This is a system API. 35 36**System capability**: SystemCapability.Multimedia.SystemSound.Core 37 38| Name | Value | Description | 39| ------------------------------- |----|------------------------------------------------------------------------| 40| RINGTONE_TYPE_DEFAULT<sup>(deprecated)</sup> | 0 | Default ringtone type.<br> This enumerated value is deprecated since API version 11. You are advised to use **RINGTONE_TYPE_SIM_CARD_0** instead.| 41| RINGTONE_TYPE_SIM_CARD_0<sup>11+</sup> | 0 | Ringtone of SIM card 1. | 42| RINGTONE_TYPE_MULTISIM<sup>(deprecated)</sup> | 1 | Multi-SIM ringtone type.<br> This enumerated value is deprecated since API version 11. You are advised to use **RINGTONE_TYPE_SIM_CARD_1** instead.| 43| RINGTONE_TYPE_SIM_CARD_1<sup>11+</sup> | 1 | Ringtone of SIM card 2. | 44 45## SystemToneType<sup>11+</sup> 46 47Enumerates the system tone types. 48 49**System API**: This is a system API. 50 51**System capability**: SystemCapability.Multimedia.SystemSound.Core 52 53| Name | Value | Description | 54| ------------------------------- |-----|------------| 55| SYSTEM_TONE_TYPE_SIM_CARD_0 | 0 | SMS tone of SIM card 1.| 56| SYSTEM_TONE_TYPE_SIM_CARD_1 | 1 | SMS tone of SIM card 2.| 57| SYSTEM_TONE_TYPE_NOTIFICATION | 32 | Notification tone. | 58 59## MediaType<sup>20+</sup> 60 61Enumerates the media types. 62 63**System API**: This is a system API. 64 65**System capability**: SystemCapability.Multimedia.SystemSound.Core 66 67| Name | Value | Description | 68| ------------------------------- |-----|------------| 69| AUDIO | 0 | Audio.| 70| VIDEO | 1 | Video.| 71 72## SystemSoundError<sup>20+</sup> 73 74Enumerates the types of errors available for system sounds. 75 76**System API**: This is a system API. 77 78**System capability**: SystemCapability.Multimedia.SystemSound.Core 79 80| Name | Value | Description | 81| -----------------------------|-----|------------| 82| ERROR_IO | 5400103 | I/O error. | 83| ERROR_OK | 20700000 | No error. | 84| ERROR_TYPE_MISMATCH | 20700001 | Type mismatch. | 85| ERROR_UNSUPPORTED_OPERATION | 20700003 | Unsupported operation. | 86| ERROR_DATA_TOO_LARGE | 20700004 | Data size exceeds the upper limit. | 87| ERROR_TOO_MANY_FILES | 20700005 | File count exceeds the upper limit. | 88| ERROR_INSUFFICIENT_ROM | 20700006 | Insufficient ROM space. | 89| ERROR_INVALID_PARAM | 20700007 | Invalid parameter. | 90 91## ToneCustomizedType<sup>12+</sup> 92 93Enumerates the tone customization types. 94 95**System API**: This is a system API. 96 97**System capability**: SystemCapability.Multimedia.SystemSound.Core 98 99| Name | Value | Description | 100| ----------------------------|-----|------------| 101| PRE_INSTALLED<sup>12+</sup> | 0 | Preinstalled tone.| 102| CUSTOMIZED<sup>12+</sup> | 1 | Custom tone.| 103 104## ToneAttrs<sup>12+</sup> 105 106Manages tone attributes. Before calling any API in ToneAttrs<sup>12+</sup>, you must use [createCustomizedToneAttrs](#systemsoundmanagercreatecustomizedtoneattrs12), [getDefaultRingtoneAttrs](#getdefaultringtoneattrs12), or [getRingtoneAttrList](#getringtoneattrlist12) to obtain a tone instance. 107 108### getTitle<sup>12+</sup> 109 110getTitle(): string 111 112Obtains the title of this tone. 113 114**System API**: This is a system API. 115 116**System capability**: SystemCapability.Multimedia.SystemSound.Core 117 118**Return value** 119 120| Type | Description | 121|--------|-----| 122| string | Title.| 123 124**Error codes** 125 126For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 127 128| ID | Error Message | 129|---------| -------------------- | 130| 202 | Caller is not a system application. | 131 132**Example** 133 134```ts 135toneAttrs.getTitle(); 136``` 137 138### setTitle<sup>12+</sup> 139 140setTitle(title: string): void 141 142Sets the title for this tone. 143 144**System API**: This is a system API. 145 146**System capability**: SystemCapability.Multimedia.SystemSound.Core 147 148**Parameters** 149 150| Name | Type | Mandatory| Description | 151| -------| -------| ---- | ------------| 152| title | string | Yes | Title. | 153 154**Error codes** 155 156For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 157 158| ID| Error Message | 159|-------| -------------------- | 160| 202 | Caller is not a system application. | 161| 401 | The parameters check failed. | 162 163**Example** 164 165```ts 166let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 167let title = 'text'; 168toneAttrs.setTitle(title); 169``` 170 171### getFileName<sup>12+</sup> 172 173getFileName(): string 174 175Obtains the file name of this tone. 176 177**System API**: This is a system API. 178 179**System capability**: SystemCapability.Multimedia.SystemSound.Core 180 181**Return value** 182 183| Type | Description | 184|--------|------| 185| string | File name.| 186 187**Error codes** 188 189For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 190 191| ID| Error Message | 192|---------| -------------------- | 193| 202 | Caller is not a system application. | 194 195 196**Example** 197 198```ts 199toneAttrs.getFileName(); 200``` 201 202### setFileName<sup>12+</sup> 203 204setFileName(name: string): void 205 206Sets the file name for this tone. 207 208**System API**: This is a system API. 209 210**System capability**: SystemCapability.Multimedia.SystemSound.Core 211 212**Parameters** 213 214| Name| Type | Mandatory| Description | 215| ------| -------|-----| ------------| 216| name | string | Yes | File name.| 217 218**Error codes** 219 220For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 221 222| ID| Error Message | 223|-------| -------------------- | 224| 202 | Caller is not a system application. | 225| 401 | The parameters check failed. | 226 227**Example** 228 229```ts 230let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 231let fileName = 'textFileName'; 232toneAttrs.setFileName(fileName); 233``` 234 235### getUri<sup>12+</sup> 236 237getUri(): string 238 239Obtains the URI of this tone. 240 241**System API**: This is a system API. 242 243**System capability**: SystemCapability.Multimedia.SystemSound.Core 244 245**Return value** 246 247| Type | Description | 248|--------|---------------------------------------------------------| 249| string | URI, for example, **'/data/storage/el2/base/RingTone/alarms/test.ogg'**.| 250 251**Error codes** 252 253For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 254 255| ID| Error Message | 256|---------| -------------------- | 257| 202 | Caller is not a system application. | 258 259**Example** 260 261```ts 262toneAttrs.getUri(); 263``` 264 265### getCustomizedType<sup>12+</sup> 266 267getCustomizedType(): ToneCustomizedType 268 269Obtains the tone customization type. 270 271**System API**: This is a system API. 272 273**System capability**: SystemCapability.Multimedia.SystemSound.Core 274 275**Return value** 276 277| Type | Description | 278|--------------------------------------------|---------| 279| [ToneCustomizedType](#tonecustomizedtype12) | Tone customization type.| 280 281**Error codes** 282 283For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 284 285| ID | Error Message | 286|---------| -------------------- | 287| 202 | Caller is not a system application. | 288 289**Example** 290 291```ts 292toneAttrs.getCustomizedType(); 293``` 294 295### setCategory<sup>12+</sup> 296 297setCategory(category: number): void 298 299Sets a category for this tone. 300 301**System API**: This is a system API. 302 303**System capability**: SystemCapability.Multimedia.SystemSound.Core 304 305**Parameters** 306 307| Name | Type | Mandatory| Description | 308|----------| ---------| ---- |----------| 309| category | number | Yes | Category of the tone. For details, see [Constants](#constants). | 310 311**Error codes** 312 313For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 314 315| ID| Error Message | 316|-------| -------------------- | 317| 202 | Caller is not a system application. | 318| 401 | The parameters check failed. | 319 320**Example** 321 322```ts 323let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 324let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; // Change the value to the required constant. 325toneAttrs.setCategory(categoryValue); 326``` 327 328### getCategory<sup>12+</sup> 329 330getCategory(): number 331 332Obtains the category of this tone. 333 334**System API**: This is a system API. 335 336**System capability**: SystemCapability.Multimedia.SystemSound.Core 337 338**Return value** 339 340| Type | Description | 341|--------|--------| 342| number | Category of the tone. For details, see [Constants](#constants).| 343 344**Error codes** 345 346For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 347 348| ID | Error Message | 349|---------| -------------------- | 350| 202 | Caller is not a system application. | 351 352 353**Example** 354 355```ts 356toneAttrs.getCategory(); 357``` 358 359### setMediaType<sup>20+</sup> 360 361setMediaType(type: MediaType): void 362 363Sets a media type for this tone. 364 365**System API**: This is a system API. 366 367**System capability**: SystemCapability.Multimedia.SystemSound.Core 368 369**Parameters** 370 371| Name | Type | Mandatory| Description | 372|----------| ---------| ---- |----------| 373| type | [MediaType](#mediatype20) | Yes | Media type. | 374 375**Error codes** 376 377For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 378 379| ID| Error Message | 380|-------| -------------------- | 381| 202 | Caller is not a system application. | 382 383**Example** 384 385```ts 386let type: systemSoundManager.MediaType = systemSoundManager.MediaType.VIDEO; // Use the required type. 387let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 388toneAttrs.setMediaType(type); 389``` 390 391### getMediaType<sup>20+</sup> 392 393getMediaType(): MediaType 394 395Obtains the media type of this tone. 396 397**System API**: This is a system API. 398 399**System capability**: SystemCapability.Multimedia.SystemSound.Core 400 401**Return value** 402 403| Type | Description | 404|--------|--------| 405| [MediaType](#mediatype20) | Media type. If the application has not called **setMediaType** to set the media type, the default value **AUDIO** is returned.| 406 407**Error codes** 408 409For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 410 411| ID | Error Message | 412|---------| -------------------- | 413| 202 | Caller is not a system application. | 414 415**Example** 416 417```ts 418toneAttrs.getMediaType(); 419``` 420 421## ToneAttrsArray<sup>12+</sup> 422 423type ToneAttrsArray = Array<[ToneAttrs](#toneattrs12)> 424 425Defines an array of tone attributes. 426 427**System API**: This is a system API. 428 429**System capability**: SystemCapability.Multimedia.SystemSound.Core 430 431| Type | Description | 432|----------------------------------------|---------| 433| Array<[ToneAttrs](#toneattrs12)> | Array of tone attributes.| 434 435## systemSoundManager.createCustomizedToneAttrs<sup>12+</sup> 436 437createCustomizedToneAttrs(): ToneAttrs 438 439Creates customized tone attributes. 440 441**System API**: This is a system API. 442 443**System capability**: SystemCapability.Multimedia.SystemSound.Core 444 445**Return value** 446 447| Type | Description | 448|---------------------------| ------------ | 449| [ToneAttrs](#toneattrs12) | Class for tone attributes.| 450 451**Error codes** 452 453For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 454 455| ID | Error Message | 456|---------| -------------------- | 457| 202 | Caller is not a system application. | 458 459**Example** 460```ts 461let toneAttrs: systemSoundManager.ToneAttrs = systemSoundManager.createCustomizedToneAttrs(); 462``` 463## ToneHapticsFeature<sup>13+</sup> 464 465Enumerates the haptics styles for different tones. 466 467**System API**: This is a system API. 468 469**System capability**: SystemCapability.Multimedia.SystemSound.Core 470 471| Name | Value| Description | 472| ----------------------------- | -- | -------------------- | 473| STANDARD| 0 | Standard haptics style.| 474| GENTLE | 1 | Gentle haptics style.| 475 476## ToneHapticsType<sup>14+</sup> 477 478Enumerates the haptics types for different tones. 479 480**System API**: This is a system API. 481 482**System capability**: SystemCapability.Multimedia.SystemSound.Core 483 484| Name | Value| Description | 485| ------------------------|----|--------| 486| CALL_SIM_CARD_0 | 0 | Haptic feedback for ringtone on SIM card 1.| 487| CALL_SIM_CARD_1 | 1 | Haptic feedback for ringtone on SIM card 2.| 488| TEXT_MESSAGE_SIM_CARD_0 | 20 | Haptic feedback for SMS tone on SIM card 1.| 489| TEXT_MESSAGE_SIM_CARD_1 | 21 | Haptic feedback for SMS tone on SIM card 2.| 490| NOTIFICATION | 40 | Haptic feedback for notification tone.| 491 492## ToneHapticsMode<sup>14+</sup> 493 494Enumerates the haptics modes in tone playback scenarios. 495 496**System API**: This is a system API. 497 498**System capability**: SystemCapability.Multimedia.SystemSound.Core 499 500| Name | Value| Description | 501| ----------------------------- | -- | -------------------- | 502| NONE | 0 | No haptics.| 503| SYNC | 1 | Sync mode, where haptic feedback is aligned with tone playback.| 504| NON_SYNC | 2 | Non-sync mode, where haptic feedback is not aligned with tone playback.| 505 506## ToneHapticsSettings<sup>14+</sup> 507 508Describes the haptics settings of a tone. 509 510**System API**: This is a system API. 511 512**System capability**: SystemCapability.Multimedia.SystemSound.Core 513 514| Name | Type| Read-Only| Optional| Description | 515| ------------ | -- | -- | -- | -------------------- | 516| mode | [ToneHapticsMode](#tonehapticsmode14) | No| No| Haptics mode.| 517| hapticsUri | string | No| Yes| URI of the haptics resource. The URI, obtained by calling [getToneHapticsList](#gettonehapticslist14), is valid only in the non-sync mode and should be ignored in other haptics modes.| 518 519## ToneHapticsAttrs<sup>14+</sup> 520 521Manages haptics attributes of tones. Before calling any API in ToneHapticsAttrs<sup>14+</sup>, you must use [getToneHapticsList](#gettonehapticslist14) or [getHapticsAttrsSyncedWithTone](#gethapticsattrssyncedwithtone14) to obtain an instance. 522 523### getUri<sup>14+</sup> 524 525getUri(): string 526 527Obtains the URI of this haptics resource. 528 529**System API**: This is a system API. 530 531**System capability**: SystemCapability.Multimedia.SystemSound.Core 532 533**Return value** 534 535| Type | Description | 536|--------|-----| 537| string | URI, for example, **'/data/storage/el2/base/haptics/synchronized/alarms/test.json'**.| 538 539**Error codes** 540 541For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 542 543| ID | Error Message | 544|---------| -------------------- | 545| 202 | Caller is not a system application. | 546 547**Example** 548 549```ts 550toneHapticsAttrs.getUri(); 551``` 552 553### getTitle<sup>14+</sup> 554 555getTitle(): string 556 557Obtains the title of this haptics resource. 558 559**System API**: This is a system API. 560 561**System capability**: SystemCapability.Multimedia.SystemSound.Core 562 563**Return value** 564 565| Type | Description | 566|--------|-----| 567| string | Title.| 568 569**Error codes** 570 571For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 572 573| ID | Error Message | 574|---------| -------------------- | 575| 202 | Caller is not a system application. | 576 577**Example** 578 579```ts 580toneHapticsAttrs.getTitle(); 581``` 582 583### getFileName<sup>14+</sup> 584 585getFileName(): string 586 587Obtains the file name of this haptics resource. 588 589**System API**: This is a system API. 590 591**System capability**: SystemCapability.Multimedia.SystemSound.Core 592 593**Return value** 594 595| Type | Description | 596|--------|-----| 597| string | File name.| 598 599**Error codes** 600 601For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 602 603| ID | Error Message | 604|---------| -------------------- | 605| 202 | Caller is not a system application. | 606 607**Example** 608 609```ts 610toneHapticsAttrs.getFileName(); 611``` 612 613## ToneHapticsAttrsArray<sup>14+</sup> 614 615type ToneHapticsAttrsArray = Array<ToneHapticsAttrs> 616 617Describes the haptics attribute array of a tone. 618 619**System capability**: SystemCapability.Multimedia.SystemSound.Core 620 621| Type | Description | 622|----------------------------------------|---------| 623| Array<[ToneHapticsAttrs](#tonehapticsattrs14)> | Array of haptics attributes.| 624 625## systemSoundManager.getSystemSoundManager 626 627getSystemSoundManager(): SystemSoundManager 628 629Obtains a system sound manager. 630 631**System API**: This is a system API. 632 633**System capability**: SystemCapability.Multimedia.SystemSound.Core 634 635**Return value** 636 637| Type | Description | 638| ----------------------------- | ------------ | 639| [SystemSoundManager](#systemsoundmanager) | System sound manager obtained.| 640 641**Example** 642```ts 643let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 644``` 645 646## SystemSoundManager 647 648Provides APIs to manage system sounds. Before calling any API in SystemSoundManager, you must use [getSystemSoundManager](#systemsoundmanagergetsystemsoundmanager) to obtain a SystemSoundManager instance. 649 650### setSystemRingtoneUri<sup>(deprecated)</sup> 651 652setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType, callback: AsyncCallback<void>): void 653 654Sets a URI for a ringtone. This API uses an asynchronous callback to return the result. 655 656> **NOTE** 657> 658> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [setRingtoneUri](#setringtoneuri11) instead. 659 660**System API**: This is a system API. 661 662**System capability**: SystemCapability.Multimedia.SystemSound.Core 663 664**Parameters** 665 666| Name | Type | Mandatory| Description | 667| -------- | ---------------------------------------- | ---- | ------------------------ | 668| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 669| uri | string | Yes | URI of the ringtone. For details about supported resources, see [media.AVPlayer](../apis-media-kit/arkts-apis-media-AVPlayer.md).| 670| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 671| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 672 673**Example** 674 675```ts 676import { BusinessError } from '@kit.BasicServicesKit'; 677import { common } from '@kit.AbilityKit'; 678 679// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 680let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 681let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 682let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 683 684let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 685systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type, (err: BusinessError) => { 686 if (err) { 687 console.error(`Failed to set system ringtone uri. ${err}`); 688 return; 689 } 690 console.info(`Callback invoked to indicate a successful setting of the system ringtone uri.`); 691}); 692``` 693 694### setSystemRingtoneUri<sup>(deprecated)</sup> 695 696setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType): Promise<void> 697 698Sets a URI for a ringtone. This API uses a promise to return the result. 699 700> **NOTE** 701> 702> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [setRingtoneUri](#setringtoneuri11) instead. 703 704**System API**: This is a system API. 705 706**System capability**: SystemCapability.Multimedia.SystemSound.Core 707 708**Parameters** 709 710| Name | Type | Mandatory| Description | 711| -------- | ---------------------------------------- | ---- | ------------------------ | 712| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 713| uri | string | Yes | URI of the ringtone. For details about supported resources, see [media.AVPlayer](../apis-media-kit/arkts-apis-media-AVPlayer.md).| 714| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 715 716**Return value** 717 718| Type | Description | 719| ------------------- | ------------------------------- | 720| Promise<void> | Promise that returns no value.| 721 722**Example** 723 724```ts 725import { BusinessError } from '@kit.BasicServicesKit'; 726import { common } from '@kit.AbilityKit'; 727 728// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 729let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 730let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 731let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 732 733let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 734systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type).then(() => { 735 console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`); 736}).catch ((err: BusinessError) => { 737 console.error(`Failed to set the system ringtone uri ${err}`); 738}); 739``` 740 741### getSystemRingtoneUri<sup>(deprecated)</sup> 742 743getSystemRingtoneUri(context: Context, type: RingtoneType, callback: AsyncCallback<string>): void 744 745Obtains the URI of a ringtone. This API uses an asynchronous callback to return the result. 746 747> **NOTE** 748> 749> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getRingtoneUri](#getringtoneuri11) instead. 750 751**System API**: This is a system API. 752 753**System capability**: SystemCapability.Multimedia.SystemSound.Core 754 755**Parameters** 756 757| Name | Type | Mandatory| Description | 758| -------- |-----------------------------------------------------------------------| ---- | ------------------------ | 759| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 760| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 761| callback | AsyncCallback<string> | Yes | Callback used to return the result. If the operation is successful, **err** is undefined and **data** is the URI obtained; otherwise, **err** is an error object.| 762 763**Example** 764 765```ts 766import { BusinessError } from '@kit.BasicServicesKit'; 767import { common } from '@kit.AbilityKit'; 768 769// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 770let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 771let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 772 773let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 774systemSoundManagerInstance.getSystemRingtoneUri(context, type, (err: BusinessError, value: string) => { 775 if (err) { 776 console.error(`Failed to get system ringtone uri. ${err}`); 777 return; 778 } 779 console.info(`Callback invoked to indicate the value of the system ringtone uri is obtained ${value}.`); 780}); 781``` 782 783### getSystemRingtoneUri<sup>(deprecated)</sup> 784 785getSystemRingtoneUri(context: Context, type: RingtoneType): Promise<string> 786 787Obtains the URI of a ringtone. This API uses a promise to return the result. 788 789> **NOTE** 790> 791> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getRingtoneUri](#getringtoneuri11) instead. 792 793**System API**: This is a system API. 794 795**System capability**: SystemCapability.Multimedia.SystemSound.Core 796 797**Parameters** 798 799| Name | Type | Mandatory| Description | 800| -------- |----------------------------------------------------------------------| ---- | ------------------------ | 801| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 802| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 803 804**Return value** 805 806| Type | Description | 807| ------------------- | ---------------------------------- | 808| Promise<string> | Promise used to return the URI obtained.| 809 810**Example** 811 812```ts 813import { BusinessError } from '@kit.BasicServicesKit'; 814import { common } from '@kit.AbilityKit'; 815 816// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 817let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 818let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 819 820let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 821systemSoundManagerInstance.getSystemRingtoneUri(context, type).then((value: string) => { 822 console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`); 823}).catch ((err: BusinessError) => { 824 console.error(`Failed to get the system ringtone uri ${err}`); 825}); 826``` 827 828### getSystemRingtonePlayer<sup>(deprecated)</sup> 829 830getSystemRingtonePlayer(context: Context, type: RingtoneType, callback: AsyncCallback<RingtonePlayer>): void 831 832Obtains a player to play a ringtone. This API uses an asynchronous callback to return the result. 833 834> **NOTE** 835> 836> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getRingtonePlayer](#getringtoneplayer11) instead. 837 838**System API**: This is a system API. 839 840**System capability**: SystemCapability.Multimedia.SystemSound.Core 841 842**Parameters** 843 844| Name | Type | Mandatory| Description | 845| -------- | -----------------------------------------| ---- | --------------------------- | 846| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 847| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone.| 848| callback | AsyncCallback<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | Yes| Callback used to return the result. If the operation is successful, **err** is undefined and **data** is the player obtained; otherwise, **err** is an error object.| 849 850**Example** 851 852```ts 853import { BusinessError } from '@kit.BasicServicesKit'; 854import { common } from '@kit.AbilityKit'; 855 856// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 857let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 858let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 859let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 860 861let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 862systemSoundManagerInstance.getSystemRingtonePlayer(context, type, (err: BusinessError, value: systemSoundManager.RingtonePlayer) => { 863 if (err) { 864 console.error(`Failed to get system ringtone player. ${err}`); 865 return; 866 } 867 console.info(`Callback invoked to indicate the value of the system ringtone player is obtained.`); 868 systemRingtonePlayer = value; 869}); 870``` 871 872### getSystemRingtonePlayer<sup>(deprecated)</sup> 873 874getSystemRingtonePlayer(context: Context, type: RingtoneType): Promise<RingtonePlayer> 875 876Obtains a player to play a ringtone. This API uses a promise to return the result. 877 878> **NOTE** 879> 880> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getRingtonePlayer](#getringtoneplayer11) instead. 881 882**System API**: This is a system API. 883 884**System capability**: SystemCapability.Multimedia.SystemSound.Core 885 886**Parameters** 887 888| Name | Type | Mandatory| Description | 889| -------- |---------------------------------------------------------------------| ---- | --------------------------- | 890| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 891| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone.| 892 893**Return value** 894 895| Type | Description | 896| ------------------- | ------------------------------- | 897| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | Promise used to return the player obtained.| 898 899**Example** 900 901```ts 902import { BusinessError } from '@kit.BasicServicesKit'; 903import { common } from '@kit.AbilityKit'; 904 905// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 906let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 907let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 908let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 909 910let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 911systemSoundManagerInstance.getSystemRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => { 912 console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`); 913 systemRingtonePlayer = value; 914}).catch ((err: BusinessError) => { 915 console.error(`Failed to get the system ringtone player ${err}`); 916}); 917``` 918 919### setRingtoneUri<sup>11+</sup> 920 921setRingtoneUri(context: BaseContext, uri: string, type: RingtoneType): Promise<void> 922 923Sets a URI for a ringtone. This API uses a promise to return the result. 924 925**System API**: This is a system API. 926 927**System capability**: SystemCapability.Multimedia.SystemSound.Core 928 929**Parameters** 930 931| Name | Type | Mandatory| Description | 932| -------- |-------------------------------| ---- | ------------------------ | 933| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 934| uri | string | Yes | URI of the ringtone. For details about supported resources, see [media.AVPlayer](../apis-media-kit/arkts-apis-media-AVPlayer.md).| 935| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 936 937**Return value** 938 939| Type | Description | 940| ------------------- | ------------------------------- | 941| Promise<void> | Promise that returns no value.| 942 943**Error codes** 944 945For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 946 947| ID| Error Message | 948| ------- | --------------------- | 949| 202 | Caller is not a system application. | 950| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 951| 5400103 | I/O error. | 952 953**Example** 954 955```ts 956import { BusinessError } from '@kit.BasicServicesKit'; 957import { common } from '@kit.AbilityKit'; 958 959// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 960let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 961let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 962let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 963 964let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 965systemSoundManagerInstance.setRingtoneUri(context, uri, type).then(() => { 966 console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`); 967}).catch ((err: BusinessError) => { 968 console.error(`Failed to set the system ringtone uri ${err}`); 969}); 970``` 971 972### getRingtoneUri<sup>11+</sup> 973 974getRingtoneUri(context: BaseContext, type: RingtoneType): Promise<string> 975 976Obtains the URI of a ringtone. This API uses a promise to return the result. 977 978**System API**: This is a system API. 979 980**System capability**: SystemCapability.Multimedia.SystemSound.Core 981 982**Parameters** 983 984| Name | Type | Mandatory| Description | 985| -------- | -------------------------------| ---- | ------------------------ | 986| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md)| Yes | Application context. | 987| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 988 989**Return value** 990 991| Type | Description | 992| ------------------- | ---------------------------------- | 993| Promise<string> | Promise used to return the URI obtained.| 994 995**Error codes** 996 997For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 998 999| ID| Error Message | 1000| -------- | --------------------- | 1001| 202 | Caller is not a system application. | 1002| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1003| 5400103 | I/O error. | 1004 1005**Example** 1006 1007```ts 1008import { BusinessError } from '@kit.BasicServicesKit'; 1009import { common } from '@kit.AbilityKit'; 1010 1011// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1012let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1013let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 1014 1015let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1016systemSoundManagerInstance.getRingtoneUri(context, type).then((value: string) => { 1017 console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`); 1018}).catch ((err: BusinessError) => { 1019 console.error(`Failed to get the system ringtone uri ${err}`); 1020}); 1021``` 1022 1023### getRingtonePlayer<sup>11+</sup> 1024 1025getRingtonePlayer(context: BaseContext, type: RingtoneType): Promise<RingtonePlayer> 1026 1027Obtains a player to play a ringtone. This API uses a promise to return the result. 1028 1029**System API**: This is a system API. 1030 1031**System capability**: SystemCapability.Multimedia.SystemSound.Core 1032 1033**Parameters** 1034 1035| Name | Type | Mandatory| Description | 1036| -------- | --------------------------------| ---- | --------------------------- | 1037| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1038| type | [RingtoneType](#ringtonetype) | Yes | Type of the ringtone.| 1039 1040**Return value** 1041 1042| Type | Description | 1043| ------------------- | ------------------------------- | 1044| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | Promise used to return the player obtained.| 1045 1046**Error codes** 1047 1048For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1049 1050| ID| Error Message | 1051| -------- | --------------------- | 1052| 202 | Caller is not a system application. | 1053| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1054 1055**Example** 1056 1057```ts 1058import { BusinessError } from '@kit.BasicServicesKit'; 1059import { common } from '@kit.AbilityKit'; 1060 1061// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1062let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1063let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 1064let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 1065 1066let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1067systemSoundManagerInstance.getRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => { 1068 console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`); 1069 systemRingtonePlayer = value; 1070}).catch ((err: BusinessError) => { 1071 console.error(`Failed to get the system ringtone player ${err}`); 1072}); 1073``` 1074 1075### setSystemToneUri<sup>11+</sup> 1076 1077setSystemToneUri(context: BaseContext, uri: string, type: SystemToneType): Promise<void> 1078 1079Sets a URI for a system tone. This API uses a promise to return the result. 1080 1081**System API**: This is a system API. 1082 1083**System capability**: SystemCapability.Multimedia.SystemSound.Core 1084 1085**Parameters** 1086 1087| Name | Type | Mandatory| Description | 1088| -------- |-------------------------------------| ---- | ------------------------ | 1089| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1090| uri | string | Yes | URI of the system tone. For details about supported resources, see [media.AVPlayer](../apis-media-kit/arkts-apis-media-AVPlayer.md).| 1091| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system tone. | 1092 1093**Return value** 1094 1095| Type | Description | 1096| ------------------- | ------------------------------- | 1097| Promise<void> | Promise that returns no value.| 1098 1099**Error codes** 1100 1101For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1102 1103| ID| Error Message | 1104| ------- | --------------------- | 1105| 202 | Caller is not a system application. | 1106| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1107| 5400103 | I/O error. | 1108 1109**Example** 1110 1111```ts 1112import { BusinessError } from '@kit.BasicServicesKit'; 1113import { common } from '@kit.AbilityKit'; 1114 1115// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1116let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1117let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 1118let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1119 1120let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1121systemSoundManagerInstance.setSystemToneUri(context, uri, type).then(() => { 1122 console.info(`Promise returned to indicate a successful setting of the system tone uri.`); 1123}).catch ((err: BusinessError) => { 1124 console.error(`Failed to set the system tone uri ${err}`); 1125}); 1126``` 1127 1128### getSystemToneUri<sup>11+</sup> 1129 1130getSystemToneUri(context: BaseContext, type: SystemToneType): Promise<string> 1131 1132Obtains the URI of a system tone. This API uses a promise to return the result. 1133 1134**System API**: This is a system API. 1135 1136**System capability**: SystemCapability.Multimedia.SystemSound.Core 1137 1138**Parameters** 1139 1140| Name | Type | Mandatory| Description | 1141| -------- |-------------------------------------| ---- | ------------------------ | 1142| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1143| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system tone. | 1144 1145**Return value** 1146 1147| Type | Description | 1148| ------------------- | ---------------------------------- | 1149| Promise<string> | Promise used to return the URI obtained.| 1150 1151**Error codes** 1152 1153For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1154 1155| ID| Error Message | 1156| ------- | --------------------- | 1157| 202 | Caller is not a system application. | 1158| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1159| 5400103 | I/O error. | 1160 1161**Example** 1162 1163```ts 1164import { BusinessError } from '@kit.BasicServicesKit'; 1165import { common } from '@kit.AbilityKit'; 1166 1167// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1168let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1169let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1170 1171let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1172systemSoundManagerInstance.getSystemToneUri(context, type).then((value: string) => { 1173 console.info(`Promise returned to indicate that the value of the system tone uri is obtained ${value}.`); 1174}).catch ((err: BusinessError) => { 1175 console.error(`Failed to get the system tone uri ${err}`); 1176}); 1177``` 1178 1179### getSystemTonePlayer<sup>11+</sup> 1180 1181getSystemTonePlayer(context: BaseContext, type: SystemToneType): Promise<SystemTonePlayer> 1182 1183Obtains a player to play a system tone. This API uses a promise to return the result. 1184 1185**System API**: This is a system API. 1186 1187**System capability**: SystemCapability.Multimedia.SystemSound.Core 1188 1189**Parameters** 1190 1191| Name | Type | Mandatory| Description | 1192| -------- |-------------------------------------| ---- | --------------------------- | 1193| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1194| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system tone.| 1195 1196**Return value** 1197 1198| Type | Description | 1199|--------------------------------------------------------------------------------------------------| ------------------------------- | 1200| Promise<[SystemTonePlayer](js-apis-inner-multimedia-systemTonePlayer-sys.md#systemtoneplayer)> | Promise used to return the player obtained.| 1201 1202**Error codes** 1203 1204For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1205 1206| ID| Error Message | 1207| ------- | --------------------- | 1208| 202 | Caller is not a system application. | 1209| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1210 1211**Example** 1212 1213```ts 1214import { BusinessError } from '@kit.BasicServicesKit'; 1215import { common } from '@kit.AbilityKit'; 1216 1217// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1218let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1219let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1220let systemTonePlayer: systemSoundManager.SystemTonePlayer | undefined = undefined; 1221 1222let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1223systemSoundManagerInstance.getSystemTonePlayer(context, type).then((value: systemSoundManager.SystemTonePlayer) => { 1224 console.info(`Promise returned to indicate that the value of the system tone player is obtained.`); 1225 systemTonePlayer = value; 1226}).catch ((err: BusinessError) => { 1227 console.error(`Failed to get the system tone player ${err}`); 1228}); 1229``` 1230 1231### getDefaultRingtoneAttrs<sup>12+</sup> 1232 1233getDefaultRingtoneAttrs(context: BaseContext, type: RingtoneType): Promise<ToneAttrs> 1234 1235Obtains the attributes of the default ringtone. This API uses a promise to return the result. 1236 1237**System API**: This is a system API. 1238 1239**System capability**: SystemCapability.Multimedia.SystemSound.Core 1240 1241**Parameters** 1242 1243| Name | Type | Mandatory| Description | 1244| -------- |-------------------------------------| ---- | --------------------------- | 1245| context |[BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1246| type |[RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 1247 1248**Return value** 1249 1250| Type | Description | 1251|--------------------------------------------------------------------------------------------------| ------------------------------- | 1252| Promise<[ToneAttrs](#toneattrs12)> | Promise used to return the attributes of the default ringtone.| 1253 1254**Error codes** 1255 1256For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1257 1258| ID| Error Message | 1259| ------- | --------------------- | 1260| 202 | Caller is not a system application. | 1261| 401 | The parameters check failed. | 1262| 5400103 | I/O error. | 1263 1264**Example** 1265 1266```ts 1267import { BusinessError } from '@kit.BasicServicesKit'; 1268import { common } from '@kit.AbilityKit'; 1269 1270// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1271let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1272let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 1273 1274let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1275systemSoundManagerInstance.getDefaultRingtoneAttrs(context, type).then((value: systemSoundManager.ToneAttrs) => { 1276 console.info(`Promise returned to indicate that the value of the attributes of the default ringtone is obtained.`); 1277}).catch ((err: BusinessError) => { 1278 console.error(`Failed to get the default ring tone attrs ${err}`); 1279}); 1280``` 1281 1282### getRingtoneAttrList<sup>12+</sup> 1283 1284getRingtoneAttrList(context: BaseContext, type: RingtoneType): Promise<ToneAttrsArray> 1285 1286Obtains an array of attributes of ringtones. This API uses a promise to return the result. 1287 1288**System API**: This is a system API. 1289 1290**System capability**: SystemCapability.Multimedia.SystemSound.Core 1291 1292**Parameters** 1293 1294| Name | Type | Mandatory| Description | 1295| -------- |-------------------------------------| ---- | --------------------------- | 1296| context |[BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1297| type |[RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 1298 1299**Return value** 1300 1301| Type | Description | 1302|--------------------------------------------------------------------------------------------------| ------------------------------- | 1303| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise used to return an array of the attributes of ringtones.| 1304 1305**Error codes** 1306 1307For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1308 1309| ID| Error Message | 1310| ------- | --------------------- | 1311| 202 | Caller is not a system application. | 1312| 401 | The parameters check failed. | 1313| 5400103 | I/O error. | 1314 1315**Example** 1316 1317```ts 1318import { BusinessError } from '@kit.BasicServicesKit'; 1319import { common } from '@kit.AbilityKit'; 1320 1321// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1322let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1323let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 1324 1325let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1326systemSoundManagerInstance.getRingtoneAttrList(context, type).then((value: systemSoundManager.ToneAttrsArray) => { 1327 console.info(`Promise returned to indicate that the value of the attribute list of ringtone is obtained.`); 1328}).catch ((err: BusinessError) => { 1329 console.error(`Failed to get the attribute list of ringtone ${err}`); 1330}); 1331``` 1332 1333### getDefaultSystemToneAttrs<sup>12+</sup> 1334 1335getDefaultSystemToneAttrs(context: BaseContext, type: SystemToneType): Promise<ToneAttrs> 1336 1337Obtains the attributes of the default system tone. This API uses a promise to return the result. 1338 1339**System API**: This is a system API. 1340 1341**System capability**: SystemCapability.Multimedia.SystemSound.Core 1342 1343**Parameters** 1344 1345| Name | Type | Mandatory| Description | 1346| -------- |-----------------------------------------------------------------------------| ---- | --------------------------- | 1347| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1348| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system tone.| 1349 1350**Return value** 1351 1352| Type | Description | 1353|-----------------------------------------|----------------------| 1354| Promise<[ToneAttrs](#toneattrs12)> | Promise used to return the attributes of the default system tone.| 1355 1356**Error codes** 1357 1358For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1359 1360| ID| Error Message | 1361| ------- | --------------------- | 1362| 202 | Caller is not a system application. | 1363| 401 | The parameters check failed. | 1364| 5400103 | I/O error. | 1365 1366**Example** 1367 1368```ts 1369import { BusinessError } from '@kit.BasicServicesKit'; 1370import { common } from '@kit.AbilityKit'; 1371 1372// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1373let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1374let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1375 1376let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1377systemSoundManagerInstance.getDefaultSystemToneAttrs(context, type).then((value: systemSoundManager.ToneAttrs) => { 1378 console.info(`Promise returned to indicate that the value of the attributes of the system ringtone is obtained.`); 1379}).catch ((err: BusinessError) => { 1380 console.error(`Failed to get the system tone attrs ${err}`); 1381}); 1382``` 1383 1384### getSystemToneAttrList<sup>12+</sup> 1385 1386getSystemToneAttrList(context: BaseContext, type: SystemToneType): Promise<ToneAttrsArray> 1387 1388Obtains an array of attributes of system tones. This API uses a promise to return the result. 1389 1390**System API**: This is a system API. 1391 1392**System capability**: SystemCapability.Multimedia.SystemSound.Core 1393 1394**Parameters** 1395 1396| Name | Type | Mandatory| Description | 1397| -------- |-----------------------------------------------------------------------------| ---- | --------------------------- | 1398| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1399| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system tone. | 1400 1401**Return value** 1402 1403| Type | Description | 1404|---------------------------------------------------|------------------------| 1405| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise used to return an array of the attributes of system tones.| 1406 1407**Error codes** 1408 1409For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1410 1411| ID| Error Message | 1412| ------- | --------------------- | 1413| 202 | Caller is not a system application. | 1414| 401 | The parameters check failed. | 1415| 5400103 | I/O error. | 1416 1417**Example** 1418 1419```ts 1420import { BusinessError } from '@kit.BasicServicesKit'; 1421import { common } from '@kit.AbilityKit'; 1422 1423// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1424let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1425let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1426 1427let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1428systemSoundManagerInstance.getSystemToneAttrList(context, type).then((value: systemSoundManager.ToneAttrsArray) => { 1429 console.info(`Promise returned to indicate that the value of the attribute list of system tone is obtained.`); 1430}).catch ((err: BusinessError) => { 1431 console.error(`Failed to get the attribute list of system tone ${err}`); 1432}); 1433``` 1434 1435### getDefaultAlarmToneAttrs<sup>12+</sup> 1436 1437getDefaultAlarmToneAttrs(context: BaseContext): Promise<ToneAttrs> 1438 1439Obtains the attributes of the default alarm tone. This API uses a promise to return the result. 1440 1441**System API**: This is a system API. 1442 1443**System capability**: SystemCapability.Multimedia.SystemSound.Core 1444 1445**Parameters** 1446 1447| Name | Type | Mandatory| Description | 1448| --------|------------| ---- |-----------| 1449| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context.| 1450 1451**Return value** 1452 1453| Type | Description | 1454|-----------------------------------------|---------------------| 1455| Promise<[ToneAttrs](#toneattrs12)> | Promise used to return the attributes of the default alarm tone.| 1456 1457**Error codes** 1458 1459For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1460 1461| ID| Error Message | 1462| ------- | --------------------- | 1463| 202 | Caller is not a system application. | 1464| 401 | The parameters check failed. | 1465| 5400103 | I/O error. | 1466 1467**Example** 1468 1469```ts 1470import { BusinessError } from '@kit.BasicServicesKit'; 1471import { common } from '@kit.AbilityKit'; 1472 1473// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1474let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1475 1476let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1477systemSoundManagerInstance.getDefaultAlarmToneAttrs(context).then((value: systemSoundManager.ToneAttrs) => { 1478 console.info(`Promise returned to indicate that the value of the attributes of the default alarm tone is obtained.`); 1479}).catch ((err: BusinessError) => { 1480 console.error(`Failed to get the default alarm tone attrs ${err}`); 1481}); 1482``` 1483 1484### setAlarmToneUri<sup>12+</sup> 1485 1486setAlarmToneUri(context: Context, uri: string): Promise<void> 1487 1488Sets a URI for an alarm tone. This API uses a promise to return the result. 1489 1490**System API**: This is a system API. 1491 1492**System capability**: SystemCapability.Multimedia.SystemSound.Core 1493 1494**Parameters** 1495 1496| Name | Type | Mandatory| Description | 1497| -------- | --------- | ---- |--------------------------| 1498| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1499| uri | string | Yes | URI of the alarm tone. For details about supported resources, see [media.AVPlayer](../apis-media-kit/arkts-apis-media-AVPlayer.md).| 1500 1501**Return value** 1502 1503| Type | Description | 1504| ------------------- |----------------------| 1505| Promise<void> | Promise that returns no value.| 1506 1507**Example** 1508 1509```ts 1510import { BusinessError } from '@kit.BasicServicesKit'; 1511import { common } from '@kit.AbilityKit'; 1512 1513// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1514let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1515let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 1516 1517let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1518systemSoundManagerInstance.setAlarmToneUri(context, uri).then(() => { 1519 console.info(`Promise returned to indicate a successful setting of the alarm tone uri.`); 1520}).catch ((err: BusinessError) => { 1521 console.error(`Failed to set the alarm tone uri ${err}`); 1522}); 1523``` 1524 1525### getAlarmToneUri<sup>12+</sup> 1526 1527getAlarmToneUri(context: Context): Promise<string> 1528 1529Obtains the URI of the current alarm tone. This API uses a promise to return the result. 1530 1531**System API**: This is a system API. 1532 1533**System capability**: SystemCapability.Multimedia.SystemSound.Core 1534 1535**Parameters** 1536 1537| Name | Type | Mandatory| Description | 1538| -------- | --------| ---- |-----------------| 1539| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1540 1541**Return value** 1542 1543| Type | Description | 1544|-----------------------|-----------------------| 1545| Promise<string> | Promise used to return the URI of the current alarm tone.| 1546 1547**Example** 1548 1549```ts 1550import { BusinessError } from '@kit.BasicServicesKit'; 1551import { common } from '@kit.AbilityKit'; 1552 1553// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1554let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1555 1556let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1557systemSoundManagerInstance.getAlarmToneUri(context).then((value: string) => { 1558 console.info(`Promise returned to indicate that the value of alarm tone uri.`); 1559}).catch ((err: BusinessError) => { 1560 console.error(`Failed to get the alarm tone uri ${err}`); 1561}); 1562``` 1563 1564### getAlarmToneAttrList<sup>12+</sup> 1565 1566getAlarmToneAttrList(context: BaseContext): Promise<ToneAttrsArray> 1567 1568Obtains an array of attributes of alarm tones. This API uses a promise to return the result. 1569 1570**System API**: This is a system API. 1571 1572**System capability**: SystemCapability.Multimedia.SystemSound.Core 1573 1574**Parameters** 1575 1576| Name | Type | Mandatory| Description | 1577| -------- |--------------| ---- | --------------------------- | 1578| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1579 1580**Return value** 1581 1582| Type | Description | 1583|----------------------------------------------------|----------------------| 1584| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise used to return an array of the attributes of alarm tones.| 1585 1586**Error codes** 1587 1588For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1589 1590| ID| Error Message | 1591| ------- | --------------------- | 1592| 202 | Caller is not a system application. | 1593| 401 | The parameters check failed. | 1594| 5400103 | I/O error. | 1595 1596**Example** 1597 1598```ts 1599import { BusinessError } from '@kit.BasicServicesKit'; 1600import { common } from '@kit.AbilityKit'; 1601 1602// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1603let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1604 1605let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1606systemSoundManagerInstance.getAlarmToneAttrList(context).then((value: systemSoundManager.ToneAttrsArray) => { 1607 console.info(`Promise returned to indicate that the value of the attribute list of alarm tone is obtained.`); 1608}).catch ((err: BusinessError) => { 1609 console.error(`Failed to get the attribute list of alarm tone ${err}`); 1610}); 1611``` 1612 1613### openAlarmTone<sup>12+</sup> 1614 1615openAlarmTone(context: Context, uri: string): Promise<number> 1616 1617Enables an alarm tone. This API uses a promise to return the result. 1618 1619**System API**: This is a system API. 1620 1621**System capability**: SystemCapability.Multimedia.SystemSound.Core 1622 1623**Parameters** 1624 1625| Name | Type | Mandatory| Description | 1626| -------- | ---------| ---- |-------------------------------------------------------------------------------------| 1627| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1628| uri | string | Yes | URI of the alarm tone. For details about supported resources, see [media.AVPlayer](../apis-media-kit/arkts-apis-media-AVPlayer.md).| 1629 1630**Return value** 1631 1632| Type | Description | 1633|-----------------------|----------------| 1634| Promise<number> | Promise used to return the FD.| 1635 1636**Error codes** 1637 1638For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 1639 1640| ID| Error Message | 1641| ------- | --------------------- | 1642| 202 | Caller is not a system application. | 1643| 401 | The parameters check failed. | 1644| 5400103 | I/O error. | 1645| 20700001 | Tone type mismatch, e.g. tone of uri is notification instead of alarm. | 1646 1647**Example** 1648 1649```ts 1650import { BusinessError } from '@kit.BasicServicesKit'; 1651import { common } from '@kit.AbilityKit'; 1652 1653// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1654let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1655let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 1656 1657let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1658systemSoundManagerInstance.openAlarmTone(context, uri).then((value: number) => { 1659 console.info(`Promise returned to indicate the value of fd.`); 1660}).catch ((err: BusinessError) => { 1661 console.error(`Failed to open alarm tone ${err}`); 1662}); 1663``` 1664 1665### close<sup>12+</sup> 1666 1667close(fd: number): Promise<void> 1668 1669Disables an alarm tone. This API uses a promise to return the result. 1670 1671**System API**: This is a system API. 1672 1673**System capability**: SystemCapability.Multimedia.SystemSound.Core 1674 1675**Parameters** 1676 1677| Name| Type | Mandatory| Description | 1678|-----| --------| ---- |----------------------------------------------| 1679| fd | number | Yes | File descriptor, which is obtained through [openAlarmTone](#openalarmtone12).| 1680 1681**Return value** 1682 1683| Type | Description | 1684|---------------------|----------------| 1685| Promise<void> | Promise that returns no value.| 1686 1687**Error codes** 1688 1689For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1690 1691| ID| Error Message | 1692| ------- | --------------------- | 1693| 202 | Caller is not a system application. | 1694| 401 | The parameters check failed. | 1695| 5400103 | I/O error. | 1696 1697**Example** 1698 1699```ts 1700import { BusinessError } from '@kit.BasicServicesKit'; 1701import { common } from '@kit.AbilityKit'; 1702 1703// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1704let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1705let fd = 50; // Use the FD of the target alarm tone. 1706 1707let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1708systemSoundManagerInstance.close(fd).then(() => { 1709 console.info(`Promise returned to indicate that the fd has been close.`); 1710}).catch ((err: BusinessError) => { 1711 console.error(`Failed to close fd ${err}`); 1712}); 1713``` 1714 1715### addCustomizedTone<sup>12+</sup> 1716 1717addCustomizedTone(context: BaseContext, toneAttr: ToneAttrs, externalUri: string): Promise<string> 1718 1719Adds a custom tone with a given URI to the tone library. This API uses a promise to return the result. 1720 1721**Required permissions**: ohos.permission.WRITE_RINGTONE 1722 1723**System API**: This is a system API. 1724 1725**System capability**: SystemCapability.Multimedia.SystemSound.Core 1726 1727**Parameters** 1728 1729| Name| Type | Mandatory| Description | 1730|-----|-----------| ---- |---------------| 1731| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1732| toneAttr | ToneAttrs | Yes | Attributes of the tone. | 1733| externalUri | string | Yes | URI of the tone in the external storage device.| 1734 1735**Return value** 1736 1737| Type | Description | 1738|-----------------------|-------------------------| 1739| Promise<string> | Promise used to return the URI of the tone in the tone library.| 1740 1741**Error codes** 1742 1743For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 1744 1745| ID | Error Message | 1746|---------| -------------------- | 1747| 201 | Permission denied. | 1748| 202 | Caller is not a system application. | 1749| 401 | The parameters check failed. | 1750| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1751| 5400103 | I/O error. | 1752| 20700004 | Data size exceeds the limit. | 1753| 20700005 | The number of files exceeds the limit. | 1754| 20700006 | Insufficient ROM space. | 1755 1756**Example** 1757 1758```ts 1759import { BusinessError } from '@kit.BasicServicesKit'; 1760import { common } from '@kit.AbilityKit'; 1761 1762// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1763let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1764let title = 'test'; // Set the title of the target tone. 1765let fileName = 'displayName_test'; // Set the file name of the target tone. 1766let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; 1767 1768let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 1769toneAttrs.setTitle(title); 1770toneAttrs.setFileName(fileName); 1771toneAttrs.setCategory(categoryValue); 1772 1773let path = 'file://data/test.ogg'; // Set the URI of the target tone. 1774 1775let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1776systemSoundManagerInstance.addCustomizedTone(context, toneAttrs, path).then((value: string) => { 1777 console.info(`Promise returned to indicate that the value of tone uri in ringtone library.`); 1778}).catch ((err: BusinessError) => { 1779 console.error(`Failed to add customized tone ${err}`); 1780}); 1781``` 1782 1783### addCustomizedTone<sup>12+</sup> 1784 1785addCustomizedTone(context: BaseContext, toneAttr: ToneAttrs, fd: number, offset?: number, length?: number): Promise<string> 1786 1787Adds a custom tone with a given FD to the tone library. This API uses a promise to return the result. 1788 1789**Required permissions**: ohos.permission.WRITE_RINGTONE 1790 1791**System API**: This is a system API. 1792 1793**System capability**: SystemCapability.Multimedia.SystemSound.Core 1794 1795**Parameters** 1796 1797| Name| Type | Mandatory| Description | 1798|-----|-----------|----|------------------------------------------------------------------------| 1799| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1800| toneAttr | [ToneAttrs](#toneattrs12) | Yes | Attributes of the tone. | 1801| fd | number | Yes | File descriptor, which is obtained by calling [fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen).| 1802| offset | number | No | Offset from which the data is read, in bytes. The default value is **0**. | 1803| length | number | No | Length of the data to read, in bytes. By default, the length is the total number of remaining bytes after the offset. | 1804 1805**Return value** 1806 1807| Type | Description | 1808|-----------------------|-------------------------| 1809| Promise<string> | Promise used to return the URI of the tone in the tone library.| 1810 1811**Error codes** 1812 1813For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 1814 1815| ID | Error Message | 1816|---------| -------------------- | 1817| 201 | Permission denied. | 1818| 202 | Caller is not a system application. | 1819| 401 | The parameters check failed. | 1820| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1821| 5400103 | I/O error. | 1822| 20700004 | Data size exceeds the limit. | 1823| 20700005 | The number of files exceeds the limit. | 1824| 20700006 | Insufficient ROM space. | 1825 1826**Example** 1827 1828```ts 1829import { BusinessError } from '@kit.BasicServicesKit'; 1830import { common } from '@kit.AbilityKit'; 1831 1832// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1833let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1834let title = 'test'; // Set the title of the target tone. 1835let fileName = 'displayName_test'; // Set the file name of the target tone. 1836let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; 1837 1838let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 1839toneAttrs.setTitle(title); 1840toneAttrs.setFileName(fileName); 1841toneAttrs.setCategory(categoryValue); 1842 1843let fd = 10; // Set the FD of the target tone. 1844let offset = 0; // Set the offset. 1845let length = 50; // Set the data length. 1846 1847let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1848systemSoundManagerInstance.addCustomizedTone(context, toneAttrs, fd, offset, length).then((value: string) => { 1849 console.info(`Promise returned to indicate that the value of tone uri in ringtone library.`); 1850}).catch ((err: BusinessError) => { 1851 console.error(`Failed to add customized tone ${err}`); 1852}); 1853``` 1854 1855### removeCustomizedTone<sup>12+</sup> 1856 1857removeCustomizedTone(context: BaseContext, uri: string): Promise<void> 1858 1859Removes a custom tone from the tone library. This API uses a promise to return the result. 1860 1861**Required permissions**: ohos.permission.WRITE_RINGTONE 1862 1863**System API**: This is a system API. 1864 1865**System capability**: SystemCapability.Multimedia.SystemSound.Core 1866 1867**Parameters** 1868 1869| Name| Type | Mandatory| Description | 1870|-----|-----------| ---- |---------------------------------------------------------------------------------------------------------| 1871| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1872| uri | string | Yes | Tone URI, which is obtained by using [addCustomizedTone](#addcustomizedtone12) or [getAlarmToneAttrList](#getalarmtoneattrlist12).| 1873 1874**Return value** 1875 1876| Type | Description | 1877|---------------------|-----------------------| 1878| Promise<void> | Promise that returns no value.| 1879 1880**Error codes** 1881 1882For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 1883 1884| ID | Error Message | 1885|---------| -------------------- | 1886| 201 | Permission denied. | 1887| 202 | Caller is not a system application. | 1888| 401 | The parameters check failed. | 1889| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1890| 5400103 | I/O error. | 1891 1892**Example** 1893 1894```ts 1895import { BusinessError } from '@kit.BasicServicesKit'; 1896import { common } from '@kit.AbilityKit'; 1897 1898// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1899let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1900let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 1901 1902let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1903systemSoundManagerInstance.removeCustomizedTone(context, uri).then(() => { 1904 console.info(`Promise returned to indicate that the customized tone has been deleted.`); 1905}).catch ((err: BusinessError) => { 1906 console.error(`Failed to delete customized tone ${err}`); 1907}); 1908``` 1909 1910### getToneHapticsSettings<sup>14+</sup> 1911 1912getToneHapticsSettings(context: BaseContext, type: ToneHapticsType): Promise<ToneHapticsSettings> 1913 1914Obtains the haptics settings of the tone. This API uses a promise to return the result. 1915 1916**System API**: This is a system API. 1917 1918**System capability**: SystemCapability.Multimedia.SystemSound.Core 1919 1920**Parameters** 1921 1922| Name| Type | Mandatory| Description | 1923|-----|-----------| ---- |----------------------------------------------------------------------------------| 1924| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1925| type | [ToneHapticsType](#tonehapticstype14) | Yes | Haptics type of the tone.| 1926 1927**Return value** 1928 1929| Type | Description | 1930|---------------------|-----------------------| 1931| Promise<[ToneHapticsSettings](#tonehapticssettings14)> | Promise used to return the haptics settings.| 1932 1933**Error codes** 1934 1935For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 1936 1937| ID | Error Message | 1938|---------| -------------------- | 1939| 202 | Caller is not a system application. | 1940| 401 | The parameters check failed. | 1941| 5400103 | I/O error. | 1942| 20700003 | Unsupported operation. | 1943 1944**Example** 1945 1946```ts 1947import { BusinessError } from '@kit.BasicServicesKit'; 1948import { common } from '@kit.AbilityKit'; 1949 1950// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1951let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1952let type: systemSoundManager.ToneHapticsType = systemSoundManager.ToneHapticsType.CALL_SIM_CARD_0; 1953 1954let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1955systemSoundManagerInstance.getToneHapticsSettings(context, type).then((value: systemSoundManager.ToneHapticsSettings) => { 1956 console.info(`Promise returned to indicate that the value of the tone haptics settings is obtained.`); 1957}).catch ((err: BusinessError) => { 1958 console.error(`Failed to get the tone haptics settings ${err}`); 1959}); 1960``` 1961 1962### setToneHapticsSettings<sup>14+</sup> 1963 1964setToneHapticsSettings(context: BaseContext, type: ToneHapticsType, settings: ToneHapticsSettings): Promise<void> 1965 1966Sets the haptics settings for the tone. This API uses a promise to return the result. 1967 1968**System API**: This is a system API. 1969 1970**System capability**: SystemCapability.Multimedia.SystemSound.Core 1971 1972**Parameters** 1973 1974| Name| Type | Mandatory| Description | 1975|-----|-----------| ---- |----------------------------------------------------------------------------------| 1976| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1977| type | [ToneHapticsType](#tonehapticstype14) | Yes | Haptics type of the tone.| 1978| settings | [ToneHapticsSettings](#tonehapticssettings14) | Yes | Haptics settings of the tone.| 1979 1980**Return value** 1981 1982| Type | Description | 1983|---------------------|-----------------------| 1984| Promise<void> | Promise that returns no value.| 1985 1986**Error codes** 1987 1988For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 1989 1990| ID | Error Message | 1991|---------| -------------------- | 1992| 202 | Caller is not a system application. | 1993| 401 | The parameters check failed. | 1994| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1995| 5400103 | I/O error. | 1996| 20700003 | Unsupported operation. | 1997 1998**Example** 1999 2000```ts 2001import { BusinessError } from '@kit.BasicServicesKit'; 2002import { common } from '@kit.AbilityKit'; 2003 2004// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 2005let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2006let type: systemSoundManager.ToneHapticsType = systemSoundManager.ToneHapticsType.CALL_SIM_CARD_0; 2007let toneHapticsSettings: systemSoundManager.ToneHapticsSettings = { 2008 mode: systemSoundManager.ToneHapticsMode.NON_SYNC, 2009 hapticsUri: '/data/storage/el2/base/haptics/synchronized/alarms/test.json', // Use the URI obtained through getToneHapticsList. 2010} 2011 2012let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2013systemSoundManagerInstance.setToneHapticsSettings(context, type, toneHapticsSettings).then(() => { 2014 console.info(`Promise returned to indicate a successful setting of the tone haptics.`); 2015}).catch ((err: BusinessError) => { 2016 console.error(`Failed to set the tone haptics settings ${err}`); 2017}); 2018``` 2019 2020### getToneHapticsList<sup>14+</sup> 2021 2022getToneHapticsList(context: BaseContext, isSynced: boolean): Promise<ToneHapticsAttrsArray> 2023 2024Obtains the haptics attributes of the tone in sync or non-sync mode. This API uses a promise to return the result. 2025 2026**System API**: This is a system API. 2027 2028**System capability**: SystemCapability.Multimedia.SystemSound.Core 2029 2030**Parameters** 2031 2032| Name| Type | Mandatory| Description | 2033|-----|-----------| ---- |----------------------------------------------------------------------------------| 2034| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 2035| isSynced | boolean | Yes | Whether the haptics feedback is synchronized with the tone. The value **true** means that the haptics feedback is synchronized with the tone, and **false** means the opposite.| 2036 2037**Return value** 2038 2039| Type | Description | 2040|---------------------|-----------------------| 2041| Promise<[ToneHapticsAttrsArray](#tonehapticsattrsarray14)> | Promise used to return the haptics attributes.| 2042 2043**Error codes** 2044 2045For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 2046 2047| ID | Error Message | 2048|---------| -------------------- | 2049| 202 | Caller is not a system application. | 2050| 401 | The parameters check failed. | 2051| 5400103 | I/O error. | 2052| 20700003 | Unsupported operation. | 2053 2054**Example** 2055 2056```ts 2057import { BusinessError } from '@kit.BasicServicesKit'; 2058import { common } from '@kit.AbilityKit'; 2059 2060// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 2061let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2062 2063let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2064systemSoundManagerInstance.getToneHapticsList(context, false).then((value: systemSoundManager.ToneHapticsAttrsArray) => { 2065 console.info(`Promise returned to indicate that the value of the attribute list of tone haptics is obtained.`); 2066}).catch ((err: BusinessError) => { 2067 console.error(`Failed to get the attribute list of tone haptics ${err}`); 2068}); 2069``` 2070 2071### getHapticsAttrsSyncedWithTone<sup>14+</sup> 2072 2073getHapticsAttrsSyncedWithTone(context: BaseContext, toneUri: string): Promise<ToneHapticsAttrs> 2074 2075Obtains the attributes of the haptics feedback synchronized with the tone. This API uses a promise to return the result. 2076 2077**System API**: This is a system API. 2078 2079**System capability**: SystemCapability.Multimedia.SystemSound.Core 2080 2081**Parameters** 2082 2083| Name| Type | Mandatory| Description | 2084|-----|-----------| ---- |----------------------------------------------------------------------------------| 2085| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 2086| toneUri | string | Yes | URI of the tone. The URI can be obtained by calling [getRingtoneAttrList](#getringtoneattrlist12) or [getSystemToneAttrList](#getsystemtoneattrlist12).| 2087 2088**Return value** 2089 2090| Type | Description | 2091|---------------------|-----------------------| 2092| Promise<[ToneHapticsAttrs](#tonehapticsattrs14)> | Promise used to return the haptics attributes.| 2093 2094**Error codes** 2095 2096For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 2097 2098| ID | Error Message | 2099|---------| -------------------- | 2100| 202 | Caller is not a system application. | 2101| 401 | The parameters check failed. | 2102| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 2103| 5400103 | I/O error. | 2104| 20700003 | Unsupported operation. | 2105 2106**Example** 2107 2108```ts 2109import { BusinessError } from '@kit.BasicServicesKit'; 2110import { common } from '@kit.AbilityKit'; 2111 2112// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 2113let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2114let toneUri: string = '/data/storage/el2/base/RingTone/alarms/test.ogg'; // Use the actual URI of the ringtone. 2115 2116let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2117systemSoundManagerInstance.getHapticsAttrsSyncedWithTone(context, toneUri).then((value: systemSoundManager.ToneHapticsAttrs) => { 2118 console.info(`Promise returned to indicate that the value of the attribute of tone haptics is obtained.`); 2119}).catch ((err: BusinessError) => { 2120 console.error(`Failed to get the attribute of tone haptics ${err}`); 2121}); 2122``` 2123 2124### openToneHaptics<sup>14+</sup> 2125 2126openToneHaptics(context: Context, hapticsUri: string): Promise<number> 2127 2128Enables haptics for the tone. This API uses a promise to return the result. 2129 2130**System API**: This is a system API. 2131 2132**System capability**: SystemCapability.Multimedia.SystemSound.Core 2133 2134**Parameters** 2135 2136| Name | Type | Mandatory| Description | 2137| -------- | ---------| ---- |-------------------------------------------------------------------------------------| 2138| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 2139| hapticsUri | string | Yes | URI of the haptics resource. For details about supported resources, see [media.AVPlayer](../apis-media-kit/arkts-apis-media-AVPlayer.md).| 2140 2141**Return value** 2142 2143| Type | Description | 2144|-----------------------|----------------| 2145| Promise<number> | Promise used to return the FD.| 2146 2147**Error codes** 2148 2149For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 2150 2151| ID| Error Message | 2152| ------- | --------------------- | 2153| 202 | Caller is not a system application. | 2154| 401 | The parameters check failed. | 2155| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 2156| 5400103 | I/O error. | 2157| 20700003 | Unsupported operation. | 2158 2159**Example** 2160 2161```ts 2162import { BusinessError } from '@kit.BasicServicesKit'; 2163import { common } from '@kit.AbilityKit'; 2164 2165// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 2166let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2167let hapticsUri = '/data/storage/el2/base/haptics/synchronized/alarms/test.json'; // Use the actual URI of the haptics resource. 2168 2169let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2170systemSoundManagerInstance.openToneHaptics(context, hapticsUri).then((value: number) => { 2171 console.info(`Promise returned to indicate the value of fd.`); 2172}).catch ((err: BusinessError) => { 2173 console.error(`Failed to open haptics ${err}`); 2174}); 2175``` 2176 2177### getCurrentRingtoneAttribute<sup>20+</sup> 2178 2179getCurrentRingtoneAttribute(type: RingtoneType): Promise<ToneAttrs> 2180 2181Obtains the attributes of the ringtone in use. This API uses a promise to return the result. 2182 2183**System API**: This is a system API. 2184 2185**System capability**: SystemCapability.Multimedia.SystemSound.Core 2186 2187**Parameters** 2188 2189| Name | Type | Mandatory| Description | 2190| -------- |-------------------------------------| ---- | --------------------------- | 2191| type |[RingtoneType](#ringtonetype) | Yes | Type of the ringtone. | 2192 2193**Return value** 2194 2195| Type | Description | 2196|-----------------------|----------------| 2197| Promise<[ToneAttrs](#toneattrs12)> | Promise used to return the attributes of the ringtone.| 2198 2199**Error codes** 2200 2201For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](../apis-media-kit/errorcode-media.md). 2202 2203| ID| Error Message | 2204| ------- | --------------------- | 2205| 202 | Caller is not a system application. | 2206| 5400103 | I/O error. | 2207 2208**Example** 2209 2210```ts 2211import { BusinessError } from '@kit.BasicServicesKit'; 2212 2213let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 2214 2215let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2216systemSoundManagerInstance.getCurrentRingtoneAttribute(type).then((value: systemSoundManager.ToneAttrs) => { 2217 console.info(`Promise returned to indicate that the value of the attributes of the current ringtone is obtained.`); 2218}).catch ((err: BusinessError) => { 2219 console.error(`Failed to get the current ringtone attribute ${err}`); 2220}); 2221``` 2222 2223### openToneList<sup>20+</sup> 2224 2225openToneList(uriList: Array\<string>): Promise\<Array\<[string, number, SystemSoundError]>> 2226 2227Obtains an array of attributes of ringtones. This API uses a promise to return the result. 2228 2229**System API**: This is a system API. 2230 2231**System capability**: SystemCapability.Multimedia.SystemSound.Core 2232 2233**Parameters** 2234 2235| Name | Type | Mandatory| Description | 2236| -------- | ---------| ---- |-----------------------| 2237| uriList | Array\<string>| Yes | URI list of the ringtones. The number of URIs cannot exceed 1024. | 2238 2239**Return value** 2240 2241| Type | Description | 2242|-----------------------|----------------| 2243| Promise\<Array\<[string, number, [SystemSoundError](#systemsounderror20)]>> | Promise used to return the result. The first parameter in the array is **uri**, the second parameter is **fd**, and the third parameter is the result of opening that URI.| 2244 2245**Error codes** 2246 2247For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ring Error Codes](./errorcode-ringtone.md). 2248 2249| ID| Error Message | 2250| ------- | --------------------- | 2251| 202 | Caller is not a system application. | 2252| 20700007 | Parameter is invalid, e.g. the length of uriList is too long. | 2253 2254**Example** 2255 2256```ts 2257import { BusinessError } from '@kit.BasicServicesKit'; 2258 2259let ringPath: string = ''; 2260let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2261let result: systemSoundManager.ToneAttrs = systemSoundManagerInstance.getCurrentRingtoneAttribute(systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0 ); 2262ringPath = result.getUri(); 2263 2264systemSoundManagerInstance.openToneList([ringPath]).then((value: systemSoundManager.ToneAttrsArray) => { 2265 console.info(`Promise returned to indicate that the value of the attribute list of system ringtones is obtained.`); 2266}).catch ((err: BusinessError) => { 2267 console.error(`Failed to get the attribute list of system ringtones ${err}`); 2268}); 2269``` 2270 2271### removeCustomizedToneList<sup>20+</sup> 2272 2273removeCustomizedToneList(uriList: Array\<string>): Promise\<Array\<[string, SystemSoundError]>> 2274 2275Removes a list of custom tones in batch. This API uses a promise to return the result. 2276 2277**System API**: This is a system API. 2278 2279**Required permissions**: ohos.permission.WRITE_RINGTONE 2280 2281**System capability**: SystemCapability.Multimedia.SystemSound.Core 2282 2283**Parameters** 2284 2285| Name | Type | Mandatory| Description | 2286| -------- | ---------| ---- |----------------------------------| 2287| uriList | Array\<string>| Yes | URI list of the ringtones. The number of URIs cannot exceed 1024. | 2288 2289**Return value** 2290 2291| Type | Description | 2292|-----------------------|----------------| 2293| Promise\<Array\<[string, [SystemSoundError](#systemsounderror20)]>> | Promise used to return the result. The first parameter in the array is **uri**, and the second parameter is the result of removing that URI.| 2294 2295**Error codes** 2296 2297For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ring Error Codes](./errorcode-ringtone.md). 2298 2299| ID| Error Message | 2300| ------- | --------------------- | 2301| 201 | Permission denied. | 2302| 202 | Caller is not a system application. | 2303| 20700007 | Parameter is invalid, e.g. the length of uriList is too long. | 2304 2305**Example** 2306 2307```ts 2308import { BusinessError } from '@kit.BasicServicesKit'; 2309 2310let ringPath: string = ''; 2311let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2312let result: systemSoundManager.ToneAttrs = systemSoundManagerInstance.getCurrentRingtoneAttribute(systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0 ); 2313ringPath = result.getUri(); 2314 2315systemSoundManagerInstance.removeCustomizedToneList([ringPath]).then((value: systemSoundManager.ToneAttrsArray) => { 2316 console.info(`Promise returned to indicate that the customized tone list has been deleted.`); 2317}).catch ((err: BusinessError) => { 2318 console.error(`Failed to delete customized tone list ${err}`); 2319}); 2320``` 2321 2322## RingtonePlayer<sup>10+</sup> 2323 2324type RingtonePlayer = _RingtonePlayer; 2325 2326Defines a ringtone player. 2327 2328**System capability**: SystemCapability.Multimedia.SystemSound.Core 2329 2330| Type |Description | 2331|-----------------|-------| 2332| _RingtonePlayer | Ringtone player.| 2333 2334## SystemTonePlayer<sup>11+</sup> 2335 2336type SystemTonePlayer = _SystemTonePlayer; 2337 2338Defines a system tone player. 2339 2340**System capability**: SystemCapability.Multimedia.SystemSound.Core 2341 2342| Type | Description | 2343|-----------------|-----------| 2344| _SystemTonePlayer | System tone player.| 2345 2346## RingtoneOptions<sup>10+</sup> 2347 2348type RingtoneOptions = _RingtoneOptions; 2349 2350Defines the configuration of a ringtone player. 2351 2352**System capability**: SystemCapability.Multimedia.SystemSound.Core 2353 2354| Type | Description | 2355|-----------------|-------------| 2356| _RingtoneOptions | Configuration of a ringtone player.| 2357 2358## SystemToneOptions<sup>11+</sup> 2359 2360type SystemToneOptions = _SystemToneOptions; 2361 2362Defines the configuration of a system tone player. 2363 2364**System capability**: SystemCapability.Multimedia.SystemSound.Core 2365 2366| Type | Description | 2367|-----------------|---------------| 2368| _SystemToneOptions | Configuration of a system tone player.| 2369<!--no_check-->