1# @ohos.multimedia.systemSoundManager (System Sound Management) (System API) 2 3The **systemSoundManager** module provides basic capabilities for managing system sounds, including setting and obtaining system ringtones and obtaining a player to play the system 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 | Value | Description | 23|------------------------------------------|-----|---------| 24| TONE_CATEGORY_RINGTONE<sup>12+</sup> | 1 | Ringtone. | 25| TONE_CATEGORY_TEXT_MESSAGE<sup>12+</sup> | 2 | SMS alert tone.| 26| TONE_CATEGORY_NOTIFICATION<sup>12+</sup> | 4 | Notification alert tone.| 27| TONE_CATEGORY_ALARM<sup>12+</sup> | 8 | Alarm alert tone.| 28 29## RingtoneType 30 31Enumerates the ringtone types. 32 33**System API**: This is a system API. 34 35**System capability**: SystemCapability.Multimedia.SystemSound.Core 36 37| Name | Value | Description | 38| ------------------------------- |----|------------------------------------------------------------------------| 39| 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.| 40| RINGTONE_TYPE_SIM_CARD_0<sup>11+</sup> | 0 | Ringtone of SIM card 1. | 41| 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.| 42| RINGTONE_TYPE_SIM_CARD_1<sup>11+</sup> | 1 | Ringtone of SIM card 2. | 43 44## SystemToneType<sup>11+</sup> 45 46Enumerates the system alert tone types. 47 48**System API**: This is a system API. 49 50**System capability**: SystemCapability.Multimedia.SystemSound.Core 51 52| Name | Value | Description | 53| ------------------------------- |-----|------------| 54| SYSTEM_TONE_TYPE_SIM_CARD_0 | 0 | SMS alert tone of SIM card 1.| 55| SYSTEM_TONE_TYPE_SIM_CARD_1 | 1 | SMS alert tone of SIM card 2.| 56| SYSTEM_TONE_TYPE_NOTIFICATION | 32 | Notification alert tone. | 57 58 59## ToneCustomizedType<sup>12+</sup> 60 61Enumerates the tone customization 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| PRE_INSTALLED<sup>12+</sup> | 0 | Preinstalled tone.| 70| CUSTOMIZED<sup>12+</sup> | 1 | Customized tone.| 71 72## ToneAttrs<sup>12+</sup> 73 74Manages 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. 75 76### getTitle<sup>12+</sup> 77 78getTitle(): string 79 80Obtains the title of this tone. 81 82**System API**: This is a system API. 83 84**System capability**: SystemCapability.Multimedia.SystemSound.Core 85 86**Return value** 87 88| Type | Description | 89|--------|-----| 90| string | Title.| 91 92**Error codes** 93 94| ID | Error Message | 95|---------| -------------------- | 96| 202 | Caller is not a system application. | 97 98**Example** 99 100```ts 101toneAttrs.getTitle(); 102``` 103 104### setTitle<sup>12+</sup> 105 106setTitle(title: string): void 107 108Sets the title for this tone. 109 110**System API**: This is a system API. 111 112**System capability**: SystemCapability.Multimedia.SystemSound.Core 113 114**Parameters** 115 116| Name | Type | Mandatory| Description | 117| -------| -------| ---- | ------------| 118| title | string | Yes | Title. | 119 120**Error codes** 121 122| ID| Error Message | 123|-------| -------------------- | 124| 202 | Caller is not a system application. | 125| 401 | The parameters check failed. | 126 127**Example** 128 129```ts 130let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 131let title = 'text'; 132toneAttrs.setTitle(title); 133``` 134 135### getFileName<sup>12+</sup> 136 137getFileName(): string 138 139Obtains the file name of this tone. 140 141**System API**: This is a system API. 142 143**System capability**: SystemCapability.Multimedia.SystemSound.Core 144 145**Return value** 146 147| Type | Description | 148|--------|------| 149| string | File name.| 150 151**Error codes** 152 153| ID| Error Message | 154|---------| -------------------- | 155| 202 | Caller is not a system application. | 156 157 158**Example** 159 160```ts 161toneAttrs.getFileName(); 162``` 163 164### setFileName<sup>12+</sup> 165 166setFileName(name: string): void 167 168Sets the file name for this tone. 169 170**System API**: This is a system API. 171 172**System capability**: SystemCapability.Multimedia.SystemSound.Core 173 174**Parameters** 175 176| Name| Type | Mandatory| Description | 177| ------| -------|-----| ------------| 178| name | string | Yes | File name.| 179 180**Error codes** 181 182| ID| Error Message | 183|-------| -------------------- | 184| 202 | Caller is not a system application. | 185| 401 | The parameters check failed. | 186 187**Example** 188 189```ts 190let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 191let fileName = 'textFileName'; 192toneAttrs.setFileName(fileName); 193``` 194 195### getUri<sup>12+</sup> 196 197getUri(): string 198 199Obtains the URI of this tone. 200 201**System API**: This is a system API. 202 203**System capability**: SystemCapability.Multimedia.SystemSound.Core 204 205**Return value** 206 207| Type | Description | 208|--------|---------------------------------------------------------| 209| string | URI, for example, **'/data/storage/el2/base/RingTone/alarms/test.ogg'**.| 210 211**Error codes** 212 213| ID| Error Message | 214|---------| -------------------- | 215| 202 | Caller is not a system application. | 216 217**Example** 218 219```ts 220toneAttrs.getUri(); 221``` 222 223### getCustomizedType<sup>12+</sup> 224 225getCustomizedType(): string 226 227Obtains the tone customization type. 228 229**System API**: This is a system API. 230 231**System capability**: SystemCapability.Multimedia.SystemSound.Core 232 233**Return value** 234 235| Type | Description | 236|--------------------------------------------|---------| 237| [ToneCustomizedType](#tonecustomizedtype12) | Tone customization type.| 238 239**Error codes** 240 241| ID | Error Message | 242|---------| -------------------- | 243| 202 | Caller is not a system application. | 244 245**Example** 246 247```ts 248toneAttrs.getCustomizedType(); 249``` 250 251### setCategory<sup>12+</sup> 252 253setCategory(category: number): void 254 255Sets a category for this tone. 256 257**System API**: This is a system API. 258 259**System capability**: SystemCapability.Multimedia.SystemSound.Core 260 261**Parameters** 262 263| Name | Type | Mandatory| Description | 264|----------| ---------| ---- |----------| 265| category | number | Yes | Category of the tone. For details, see [Constants](#constants). | 266 267**Error codes** 268 269| ID| Error Message | 270|-------| -------------------- | 271| 202 | Caller is not a system application. | 272| 401 | The parameters check failed. | 273 274**Example** 275 276```ts 277let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 278let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; // Change the value to the required constant. 279toneAttrs.setCategory(categoryValue); 280``` 281 282### getCategory<sup>12+</sup> 283 284getCategory(): string 285 286Obtains the category of this tone. 287 288**System API**: This is a system API. 289 290**System capability**: SystemCapability.Multimedia.SystemSound.Core 291 292**Return value** 293 294| Type | Description | 295|--------|--------| 296| number | Category of the tone. For details, see [Constants](#constants).| 297 298**Error codes** 299 300| ID | Error Message | 301|---------| -------------------- | 302| 202 | Caller is not a system application. | 303 304 305**Example** 306 307```ts 308toneAttrs.getCategory(); 309``` 310 311## ToneAttrsArray<sup>12+</sup> 312 313type ToneAttrsArray = Array<[ToneAttrs](#toneattrs12)> 314 315Defines an array of tone attributes. 316 317**System capability**: SystemCapability.Multimedia.SystemSound.Core 318 319| Type | Description | 320|----------------------------------------|---------| 321| Array<[ToneAttrs](#toneattrs12)> | Array of tone attributes.| 322 323## systemSoundManager.createCustomizedToneAttrs<sup>12+</sup> 324 325createCustomizedToneAttrs(): ToneAttrs 326 327Creates customized tone attributes. 328 329**System API**: This is a system API. 330 331**System capability**: SystemCapability.Multimedia.SystemSound.Core 332 333**Return value** 334 335| Type | Description | 336|---------------------------| ------------ | 337| [ToneAttrs](#toneattrs12) | Class for tone attributes.| 338 339**Error codes** 340 341For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 342 343| ID | Error Message | 344|---------| -------------------- | 345| 202 | Caller is not a system application. | 346 347**Example** 348```ts 349let toneAttrs: systemSoundManager.ToneAttrs = systemSoundManager.createCustomizedToneAttrs(); 350``` 351## ToneHapticsFeature<sup>12+</sup> 352 353Enumerates the haptics styles for system ringtones. 354 355**System API**: This is a system API. 356 357**System capability**: SystemCapability.Multimedia.SystemSound.Core 358 359| Name | Value| Description | 360| ----------------------------- | -- | -------------------- | 361| STANDARD| 0 | Standard haptics style.| 362| GENTLE | 1 | Gentle haptics style.| 363 364## systemSoundManager.getSystemSoundManager 365 366getSystemSoundManager(): SystemSoundManager 367 368Obtains a system sound manager. 369 370**System API**: This is a system API. 371 372**System capability**: SystemCapability.Multimedia.SystemSound.Core 373 374**Return value** 375 376| Type | Description | 377| ----------------------------- | ------------ | 378| [SystemSoundManager](#systemsoundmanager) | System sound manager obtained.| 379 380**Example** 381```ts 382let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 383``` 384 385## SystemSoundManager 386 387Provides APIs to manage system sounds. Before calling any API in **SystemSoundManager**, you must use [getSystemSoundManager](#systemsoundmanagergetsystemsoundmanager) to create a **SystemSoundManager** instance. 388 389### setSystemRingtoneUri<sup>(deprecated)</sup> 390 391setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType, callback: AsyncCallback<void>): void 392 393Sets a URI for a system ringtone. This API uses an asynchronous callback to return the result. 394 395> **NOTE** 396> 397> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [setRingtoneUri](#setringtoneuri11) instead. 398 399**System API**: This is a system API. 400 401**System capability**: SystemCapability.Multimedia.SystemSound.Core 402 403**Parameters** 404 405| Name | Type | Mandatory| Description | 406| -------- | ---------------------------------------- | ---- | ------------------------ | 407| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 408| uri | string | Yes | URI of the system ringtone. For details, see [media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9).| 409| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone. | 410| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 411 412**Example** 413 414```ts 415import { BusinessError } from '@kit.BasicServicesKit'; 416import { common } from '@kit.AbilityKit'; 417 418let context: Context = getContext(this); 419let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 420let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 421 422let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 423systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type, (err: BusinessError) => { 424 if (err) { 425 console.error(`Failed to set system ringtone uri. ${err}`); 426 return; 427 } 428 console.info(`Callback invoked to indicate a successful setting of the system ringtone uri.`); 429}); 430``` 431 432### setSystemRingtoneUri<sup>(deprecated)</sup> 433 434setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType): Promise<void> 435 436Sets a URI for a system ringtone. This API uses a promise to return the result. 437 438> **NOTE** 439> 440> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [setRingtoneUri](#setringtoneuri11) instead. 441 442**System API**: This is a system API. 443 444**System capability**: SystemCapability.Multimedia.SystemSound.Core 445 446**Parameters** 447 448| Name | Type | Mandatory| Description | 449| -------- | ---------------------------------------- | ---- | ------------------------ | 450| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 451| uri | string | Yes | URI of the system ringtone. For details, see [media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9).| 452| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone. | 453 454**Return value** 455 456| Type | Description | 457| ------------------- | ------------------------------- | 458| Promise<void> | Promise used to return the result. | 459 460**Example** 461 462```ts 463import { BusinessError } from '@kit.BasicServicesKit'; 464import { common } from '@kit.AbilityKit'; 465 466let context: Context = getContext(this); 467let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 468let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 469 470let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 471systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type).then(() => { 472 console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`); 473}).catch ((err: BusinessError) => { 474 console.error(`Failed to set the system ringtone uri ${err}`); 475}); 476``` 477 478### getSystemRingtoneUri<sup>(deprecated)</sup> 479 480getSystemRingtoneUri(context: Context, type: RingtoneType, callback: AsyncCallback<string>): void 481 482Obtains the URI of a system ringtone. This API uses an asynchronous callback to return the result. 483 484> **NOTE** 485> 486> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getRingtoneUri](#getringtoneuri11) instead. 487 488**System API**: This is a system API. 489 490**System capability**: SystemCapability.Multimedia.SystemSound.Core 491 492**Parameters** 493 494| Name | Type | Mandatory| Description | 495| -------- |-----------------------------------------------------------------------| ---- | ------------------------ | 496| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 497| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone. | 498| callback | AsyncCallback<string> | Yes | Callback used to return the URI obtained.| 499 500**Example** 501 502```ts 503import { BusinessError } from '@kit.BasicServicesKit'; 504import { common } from '@kit.AbilityKit'; 505 506let context: Context = getContext(this); 507let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 508 509let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 510systemSoundManagerInstance.getSystemRingtoneUri(context, type, (err: BusinessError, value: string) => { 511 if (err) { 512 console.error(`Failed to get system ringtone uri. ${err}`); 513 return; 514 } 515 console.info(`Callback invoked to indicate the value of the system ringtone uri is obtained ${value}.`); 516}); 517``` 518 519### getSystemRingtoneUri<sup>(deprecated)</sup> 520 521getSystemRingtoneUri(context: Context, type: RingtoneType): Promise<string> 522 523Obtains the URI of a system ringtone. This API uses a promise to return the result. 524 525> **NOTE** 526> 527> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getRingtoneUri](#getringtoneuri11) instead. 528 529**System API**: This is a system API. 530 531**System capability**: SystemCapability.Multimedia.SystemSound.Core 532 533**Parameters** 534 535| Name | Type | Mandatory| Description | 536| -------- |----------------------------------------------------------------------| ---- | ------------------------ | 537| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 538| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone. | 539 540**Return value** 541 542| Type | Description | 543| ------------------- | ---------------------------------- | 544| Promise<string> | Promise used to return the URI obtained.| 545 546**Example** 547 548```ts 549import { BusinessError } from '@kit.BasicServicesKit'; 550import { common } from '@kit.AbilityKit'; 551 552let context: Context = getContext(this); 553let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 554 555let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 556systemSoundManagerInstance.getSystemRingtoneUri(context, type).then((value: string) => { 557 console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`); 558}).catch ((err: BusinessError) => { 559 console.error(`Failed to get the system ringtone uri ${err}`); 560}); 561``` 562 563### getSystemRingtonePlayer<sup>(deprecated)</sup> 564 565getSystemRingtonePlayer(context: Context, type: RingtoneType, callback: AsyncCallback<RingtonePlayer>): void 566 567Obtains a player to play a system ringtone. This API uses an asynchronous callback to return the result. 568 569> **NOTE** 570> 571> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getRingtonePlayer](#getringtoneplayer11) instead. 572 573**System API**: This is a system API. 574 575**System capability**: SystemCapability.Multimedia.SystemSound.Core 576 577**Parameters** 578 579| Name | Type | Mandatory| Description | 580| -------- | -----------------------------------------| ---- | --------------------------- | 581| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 582| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone.| 583| callback | AsyncCallback<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | Yes| Callback used to return the player obtained.| 584 585**Example** 586 587```ts 588import { BusinessError } from '@kit.BasicServicesKit'; 589import { common } from '@kit.AbilityKit'; 590 591let context: Context = getContext(this); 592let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 593let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 594 595let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 596systemSoundManagerInstance.getSystemRingtonePlayer(context, type, (err: BusinessError, value: systemSoundManager.RingtonePlayer) => { 597 if (err) { 598 console.error(`Failed to get system ringtone player. ${err}`); 599 return; 600 } 601 console.info(`Callback invoked to indicate the value of the system ringtone player is obtained.`); 602 systemRingtonePlayer = value; 603}); 604``` 605 606### getSystemRingtonePlayer<sup>(deprecated)</sup> 607 608getSystemRingtonePlayer(context: Context, type: RingtoneType): Promise<RingtonePlayer> 609 610Obtains a player to play a system ringtone. This API uses a promise to return the result. 611 612> **NOTE** 613> 614> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getRingtonePlayer](#getringtoneplayer11) instead. 615 616**System API**: This is a system API. 617 618**System capability**: SystemCapability.Multimedia.SystemSound.Core 619 620**Parameters** 621 622| Name | Type | Mandatory| Description | 623| -------- |---------------------------------------------------------------------| ---- | --------------------------- | 624| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 625| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone.| 626 627**Return value** 628 629| Type | Description | 630| ------------------- | ------------------------------- | 631| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | Promise used to return the player obtained.| 632 633**Example** 634 635```ts 636import { BusinessError } from '@kit.BasicServicesKit'; 637import { common } from '@kit.AbilityKit'; 638 639let context: Context = getContext(this); 640let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 641let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 642 643let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 644systemSoundManagerInstance.getSystemRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => { 645 console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`); 646 systemRingtonePlayer = value; 647}).catch ((err: BusinessError) => { 648 console.error(`Failed to get the system ringtone player ${err}`); 649}); 650``` 651 652### setRingtoneUri<sup>11+</sup> 653 654setRingtoneUri(context: BaseContext, uri: string, type: RingtoneType): Promise<void> 655 656Sets a URI for a system ringtone. This API uses a promise to return the result. 657 658**System API**: This is a system API. 659 660**System capability**: SystemCapability.Multimedia.SystemSound.Core 661 662**Parameters** 663 664| Name | Type | Mandatory| Description | 665| -------- |-------------------------------| ---- | ------------------------ | 666| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 667| uri | string | Yes | URI of the system ringtone. For details, see [media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9).| 668| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone. | 669 670**Return value** 671 672| Type | Description | 673| ------------------- | ------------------------------- | 674| Promise<void> | Promise used to return the result. | 675 676**Error codes** 677 678For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 679 680| ID| Error Message | 681| ------- | --------------------- | 682| 202 | Caller is not a system application. | 683| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 684| 5400103 | I/O error. | 685 686**Example** 687 688```ts 689import { BusinessError } from '@kit.BasicServicesKit'; 690import { common } from '@kit.AbilityKit'; 691 692let context: common.BaseContext = getContext(this); 693let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 694let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 695 696let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 697systemSoundManagerInstance.setRingtoneUri(context, uri, type).then(() => { 698 console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`); 699}).catch ((err: BusinessError) => { 700 console.error(`Failed to set the system ringtone uri ${err}`); 701}); 702``` 703 704### getRingtoneUri<sup>11+</sup> 705 706getRingtoneUri(context: BaseContext, type: RingtoneType): Promise<string> 707 708Obtains the URI of a system ringtone. This API uses a promise to return the result. 709 710**System API**: This is a system API. 711 712**System capability**: SystemCapability.Multimedia.SystemSound.Core 713 714**Parameters** 715 716| Name | Type | Mandatory| Description | 717| -------- | -------------------------------| ---- | ------------------------ | 718| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md)| Yes | Application context. | 719| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone. | 720 721**Return value** 722 723| Type | Description | 724| ------------------- | ---------------------------------- | 725| Promise<string> | Promise used to return the URI obtained.| 726 727**Error codes** 728 729For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 730 731| ID| Error Message | 732| -------- | --------------------- | 733| 202 | Caller is not a system application. | 734| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 735| 5400103 | I/O error. | 736 737**Example** 738 739```ts 740import { BusinessError } from '@kit.BasicServicesKit'; 741import { common } from '@kit.AbilityKit'; 742 743let context: common.BaseContext = getContext(this); 744let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 745 746let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 747systemSoundManagerInstance.getRingtoneUri(context, type).then((value: string) => { 748 console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`); 749}).catch ((err: BusinessError) => { 750 console.error(`Failed to get the system ringtone uri ${err}`); 751}); 752``` 753 754### getRingtonePlayer<sup>11+</sup> 755 756getRingtonePlayer(context: BaseContext, type: RingtoneType): Promise<RingtonePlayer> 757 758Obtains a player to play a system ringtone. This API uses a promise to return the result. 759 760**System API**: This is a system API. 761 762**System capability**: SystemCapability.Multimedia.SystemSound.Core 763 764**Parameters** 765 766| Name | Type | Mandatory| Description | 767| -------- | --------------------------------| ---- | --------------------------- | 768| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 769| type | [RingtoneType](#ringtonetype) | Yes | Type of the system ringtone.| 770 771**Return value** 772 773| Type | Description | 774| ------------------- | ------------------------------- | 775| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | Promise used to return the player obtained.| 776 777**Error codes** 778 779For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 780 781| ID| Error Message | 782| -------- | --------------------- | 783| 202 | Caller is not a system application. | 784| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 785 786**Example** 787 788```ts 789import { BusinessError } from '@kit.BasicServicesKit'; 790import { common } from '@kit.AbilityKit'; 791 792let context: common.BaseContext = getContext(this); 793let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 794let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 795 796let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 797systemSoundManagerInstance.getRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => { 798 console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`); 799 systemRingtonePlayer = value; 800}).catch ((err: BusinessError) => { 801 console.error(`Failed to get the system ringtone player ${err}`); 802}); 803``` 804 805### setSystemToneUri<sup>11+</sup> 806 807setSystemToneUri(context: BaseContext, uri: string, type: SystemToneType): Promise<void> 808 809Sets a URI for a system alert tone. This API uses a promise to return the result. 810 811**System API**: This is a system API. 812 813**System capability**: SystemCapability.Multimedia.SystemSound.Core 814 815**Parameters** 816 817| Name | Type | Mandatory| Description | 818| -------- |-------------------------------------| ---- | ------------------------ | 819| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 820| uri | string | Yes | URI of the system alert tone. For details, see [media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9).| 821| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system alert tone. | 822 823**Return value** 824 825| Type | Description | 826| ------------------- | ------------------------------- | 827| Promise<void> | Promise used to return the result. | 828 829**Error codes** 830 831For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 832 833| ID| Error Message | 834| ------- | --------------------- | 835| 202 | Caller is not a system application. | 836| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 837| 5400103 | I/O error. | 838 839**Example** 840 841```ts 842import { BusinessError } from '@kit.BasicServicesKit'; 843import { common } from '@kit.AbilityKit'; 844 845let context: common.BaseContext = getContext(this); 846let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 847let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 848 849let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 850systemSoundManagerInstance.setSystemToneUri(context, uri, type).then(() => { 851 console.info(`Promise returned to indicate a successful setting of the system tone uri.`); 852}).catch ((err: BusinessError) => { 853 console.error(`Failed to set the system tone uri ${err}`); 854}); 855``` 856 857### getSystemToneUri<sup>11+</sup> 858 859getSystemToneUri(context: BaseContext, type: SystemToneType): Promise<string> 860 861Obtains the URI of a system alert tone. This API uses a promise to return the result. 862 863**System API**: This is a system API. 864 865**System capability**: SystemCapability.Multimedia.SystemSound.Core 866 867**Parameters** 868 869| Name | Type | Mandatory| Description | 870| -------- |-------------------------------------| ---- | ------------------------ | 871| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 872| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system alert tone. | 873 874**Return value** 875 876| Type | Description | 877| ------------------- | ---------------------------------- | 878| Promise<string> | Promise used to return the URI obtained.| 879 880**Error codes** 881 882For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 883 884| ID| Error Message | 885| ------- | --------------------- | 886| 202 | Caller is not a system application. | 887| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 888| 5400103 | I/O error. | 889 890**Example** 891 892```ts 893import { BusinessError } from '@kit.BasicServicesKit'; 894import { common } from '@kit.AbilityKit'; 895 896let context: common.BaseContext = getContext(this); 897let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 898 899let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 900systemSoundManagerInstance.getSystemToneUri(context, type).then((value: string) => { 901 console.info(`Promise returned to indicate that the value of the system tone uri is obtained ${value}.`); 902}).catch ((err: BusinessError) => { 903 console.error(`Failed to get the system tone uri ${err}`); 904}); 905``` 906 907### getSystemTonePlayer<sup>11+</sup> 908 909getSystemTonePlayer(context: BaseContext, type: SystemToneType): Promise<SystemTonePlayer> 910 911Obtains a player to play a system alert tone. This API uses a promise to return the result. 912 913**System API**: This is a system API. 914 915**System capability**: SystemCapability.Multimedia.SystemSound.Core 916 917**Parameters** 918 919| Name | Type | Mandatory| Description | 920| -------- |-------------------------------------| ---- | --------------------------- | 921| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 922| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system alert tone.| 923 924**Return value** 925 926| Type | Description | 927|--------------------------------------------------------------------------------------------------| ------------------------------- | 928| Promise<[SystemTonePlayer](js-apis-inner-multimedia-systemTonePlayer-sys.md#systemtoneplayer)> | Promise used to return the player obtained.| 929 930**Error codes** 931 932For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 933 934| ID| Error Message | 935| ------- | --------------------- | 936| 202 | Caller is not a system application. | 937| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 938 939**Example** 940 941```ts 942import { BusinessError } from '@kit.BasicServicesKit'; 943import { common } from '@kit.AbilityKit'; 944 945let context: common.BaseContext = getContext(this); 946let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 947let systemTonePlayer: systemSoundManager.SystemTonePlayer | undefined = undefined; 948 949let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 950systemSoundManagerInstance.getSystemTonePlayer(context, type).then((value: systemSoundManager.SystemTonePlayer) => { 951 console.info(`Promise returned to indicate that the value of the system tone player is obtained.`); 952 systemTonePlayer = value; 953}).catch ((err: BusinessError) => { 954 console.error(`Failed to get the system tone player ${err}`); 955}); 956``` 957 958### getDefaultRingtoneAttrs<sup>12+</sup> 959 960getDefaultRingtoneAttrs(context: BaseContext, type: RingtoneType): Promise<ToneAttrs> 961 962Obtains the attributes of the default system ringtone. This API uses a promise to return the result. 963 964**System API**: This is a system API. 965 966**System capability**: SystemCapability.Multimedia.SystemSound.Core 967 968**Parameters** 969 970| Name | Type | Mandatory| Description | 971| -------- |-------------------------------------| ---- | --------------------------- | 972| context |[BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 973| type |[RingtoneType](#ringtonetype) | Yes | Type of the system ringtone. | 974 975**Return value** 976 977| Type | Description | 978|------------------------------------------|---------------------| 979| Promise<[ToneAttrs](#toneattrs12)> | Promise used to return the attributes of the default system ringtone.| 980 981**Error codes** 982 983For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 984 985| ID| Error Message | 986| ------- | --------------------- | 987| 202 | Caller is not a system application. | 988| 401 | The parameters check failed. | 989| 5400103 | I/O error. | 990 991**Example** 992 993```ts 994import { BusinessError } from '@kit.BasicServicesKit'; 995import { common } from '@kit.AbilityKit'; 996 997let context: common.BaseContext = getContext(this); 998let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 999 1000let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1001systemSoundManagerInstance.getDefaultRingtoneAttrs(context, type).then((value: systemSoundManager.ToneAttrs) => { 1002 console.info(`Promise returned to indicate that the value of the attributes of the default ringtone is obtained.`); 1003}).catch ((err: BusinessError) => { 1004 console.error(`Failed to get the default ring tone attrs ${err}`); 1005}); 1006``` 1007 1008### getRingtoneAttrList<sup>12+</sup> 1009 1010getRingtoneAttrList(context: BaseContext, type: RingtoneType): Promise<ToneAttrsArray> 1011 1012Obtains the list of attributes of the default system ringtone. This API uses a promise to return the result. 1013 1014**System API**: This is a system API. 1015 1016**System capability**: SystemCapability.Multimedia.SystemSound.Core 1017 1018**Parameters** 1019 1020| Name | Type | Mandatory| Description | 1021| -------- |-------------------------------------| ---- | --------------------------- | 1022| context |[BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1023| type |[RingtoneType](#ringtonetype) | Yes | Type of the system ringtone. | 1024 1025**Return value** 1026 1027| Type | Description | 1028|----------------------------------------------------|-----------------------| 1029| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise used to return an array of the attributes of the default system ringtone.| 1030 1031**Error codes** 1032 1033For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1034 1035| ID| Error Message | 1036| ------- | --------------------- | 1037| 202 | Caller is not a system application. | 1038| 401 | The parameters check failed. | 1039| 5400103 | I/O error. | 1040 1041**Example** 1042 1043```ts 1044import { BusinessError } from '@kit.BasicServicesKit'; 1045import { common } from '@kit.AbilityKit'; 1046 1047let context: common.BaseContext = getContext(this); 1048let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 1049 1050let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1051systemSoundManagerInstance.getRingtoneAttrList(context, type).then((value: systemSoundManager.ToneAttrsArray) => { 1052 console.info(`Promise returned to indicate that the value of the attribute list of ringtone is obtained.`); 1053}).catch ((err: BusinessError) => { 1054 console.error(`Failed to get the attribute list of ringtone ${err}`); 1055}); 1056``` 1057 1058### getDefaultSystemToneAttrs<sup>12+</sup> 1059 1060getDefaultSystemToneAttrs(context: BaseContext, type: SystemToneType): Promise<ToneAttrs> 1061 1062Obtains the attributes of the default system alert tone. This API uses a promise to return the result. 1063 1064**System API**: This is a system API. 1065 1066**System capability**: SystemCapability.Multimedia.SystemSound.Core 1067 1068**Parameters** 1069 1070| Name | Type | Mandatory| Description | 1071| -------- |-----------------------------------------------------------------------------| ---- | --------------------------- | 1072| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1073| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system alert tone.| 1074 1075**Return value** 1076 1077| Type | Description | 1078|-----------------------------------------|----------------------| 1079| Promise<[ToneAttrs](#toneattrs12)> | Promise used to return the attributes of the default system alert tone.| 1080 1081**Error codes** 1082 1083For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1084 1085| ID| Error Message | 1086| ------- | --------------------- | 1087| 202 | Caller is not a system application. | 1088| 401 | The parameters check failed. | 1089| 5400103 | I/O error. | 1090 1091**Example** 1092 1093```ts 1094import { BusinessError } from '@kit.BasicServicesKit'; 1095import { common } from '@kit.AbilityKit'; 1096 1097let context: common.BaseContext = getContext(this); 1098let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1099 1100let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1101systemSoundManagerInstance.getDefaultSystemToneAttrs(context, type).then((value: systemSoundManager.ToneAttrs) => { 1102 console.info(`Promise returned to indicate that the value of the attributes of the system ringtone is obtained.`); 1103}).catch ((err: BusinessError) => { 1104 console.error(`Failed to get the system tone attrs ${err}`); 1105}); 1106``` 1107 1108### getSystemToneAttrList<sup>12+</sup> 1109 1110getSystemToneAttrList(context: BaseContext, type: SystemToneType): Promise<ToneAttrsArray> 1111 1112Obtains the list of attributes of the default system alert tone. This API uses a promise to return the result. 1113 1114**System API**: This is a system API. 1115 1116**System capability**: SystemCapability.Multimedia.SystemSound.Core 1117 1118**Parameters** 1119 1120| Name | Type | Mandatory| Description | 1121| -------- |-----------------------------------------------------------------------------| ---- | --------------------------- | 1122| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1123| type | [SystemToneType](#systemtonetype11) | Yes | Type of the system alert tone. | 1124 1125**Return value** 1126 1127| Type | Description | 1128|---------------------------------------------------|------------------------| 1129| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise used to return an array of the attributes of the default system alert tone.| 1130 1131**Error codes** 1132 1133For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1134 1135| ID| Error Message | 1136| ------- | --------------------- | 1137| 202 | Caller is not a system application. | 1138| 401 | The parameters check failed. | 1139| 5400103 | I/O error. | 1140 1141**Example** 1142 1143```ts 1144import { BusinessError } from '@kit.BasicServicesKit'; 1145import { common } from '@kit.AbilityKit'; 1146 1147let context: common.BaseContext = getContext(this); 1148let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1149 1150let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1151systemSoundManagerInstance.getSystemToneAttrList(context, type).then((value: systemSoundManager.ToneAttrsArray) => { 1152 console.info(`Promise returned to indicate that the value of the attribute list of system tone is obtained.`); 1153}).catch ((err: BusinessError) => { 1154 console.error(`Failed to get the attribute list of system tone ${err}`); 1155}); 1156``` 1157 1158### getDefaultAlarmToneAttrs<sup>12+</sup> 1159 1160getDefaultAlarmToneAttrs(context: BaseContext): Promise<ToneAttrs> 1161 1162Obtains the attributes of the default alarm alert tone. This API uses a promise to return the result. 1163 1164**System API**: This is a system API. 1165 1166**System capability**: SystemCapability.Multimedia.SystemSound.Core 1167 1168**Parameters** 1169 1170| Name | Type | Mandatory| Description | 1171| --------|------------| ---- |-----------| 1172| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context.| 1173 1174**Return value** 1175 1176| Type | Description | 1177|-----------------------------------------|---------------------| 1178| Promise<[ToneAttrs](#toneattrs12)> | Promise used to return the attributes of the default alarm alert tone.| 1179 1180**Error codes** 1181 1182For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1183 1184| ID| Error Message | 1185| ------- | --------------------- | 1186| 202 | Caller is not a system application. | 1187| 401 | The parameters check failed. | 1188| 5400103 | I/O error. | 1189 1190**Example** 1191 1192```ts 1193import { BusinessError } from '@kit.BasicServicesKit'; 1194import { common } from '@kit.AbilityKit'; 1195 1196let context: common.BaseContext = getContext(this); 1197 1198let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1199systemSoundManagerInstance.getDefaultAlarmToneAttrs(context).then((value: systemSoundManager.ToneAttrs) => { 1200 console.info(`Promise returned to indicate that the value of the attributes of the default alarm tone is obtained.`); 1201}).catch ((err: BusinessError) => { 1202 console.error(`Failed to get the default alarm tone attrs ${err}`); 1203}); 1204``` 1205 1206### setAlarmToneUri<sup>12+</sup> 1207 1208setAlarmToneUri(context: Context, uri: string): Promise<void> 1209 1210Sets a URI for an alarm alert tone. This API uses a promise to return the result. 1211 1212**System API**: This is a system API. 1213 1214**System capability**: SystemCapability.Multimedia.SystemSound.Core 1215 1216**Parameters** 1217 1218| Name | Type | Mandatory| Description | 1219| -------- | --------- | ---- |--------------------------| 1220| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1221| uri | string | Yes | URI of the alarm alert tone. For details, see [media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9).| 1222 1223**Return value** 1224 1225| Type | Description | 1226| ------------------- |----------------------| 1227| Promise<void> | Promise used to return the result. | 1228 1229**Example** 1230 1231```ts 1232import { BusinessError } from '@kit.BasicServicesKit'; 1233import { common } from '@kit.AbilityKit'; 1234 1235let context: Context = getContext(this); 1236let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 1237 1238let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1239systemSoundManagerInstance.setAlarmToneUri(context, uri).then(() => { 1240 console.info(`Promise returned to indicate a successful setting of the alarm tone uri.`); 1241}).catch ((err: BusinessError) => { 1242 console.error(`Failed to set the alarm tone uri ${err}`); 1243}); 1244``` 1245 1246### getAlarmToneUri<sup>12+</sup> 1247 1248getAlarmToneUri(context: Context): Promise<string> 1249 1250Obtains the URI of an alarm alert tone. This API uses a promise to return the result. 1251 1252**System API**: This is a system API. 1253 1254**System capability**: SystemCapability.Multimedia.SystemSound.Core 1255 1256**Parameters** 1257 1258| Name | Type | Mandatory| Description | 1259| -------- | --------| ---- |-----------------| 1260| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1261 1262**Return value** 1263 1264| Type | Description | 1265|-----------------------|-----------------------| 1266| Promise<string> | Promise used to return the URI of the alarm alert tone.| 1267 1268**Example** 1269 1270```ts 1271import { BusinessError } from '@kit.BasicServicesKit'; 1272import { common } from '@kit.AbilityKit'; 1273 1274let context: Context = getContext(this); 1275 1276let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1277systemSoundManagerInstance.getAlarmToneUri(context).then((value: string) => { 1278 console.info(`Promise returned to indicate that the value of alarm tone uri.`); 1279}).catch ((err: BusinessError) => { 1280 console.error(`Failed to get the alarm tone uri ${err}`); 1281}); 1282``` 1283 1284### getAlarmToneAttrList<sup>12+</sup> 1285 1286getAlarmToneAttrList(context: BaseContext): Promise<ToneAttrsArray> 1287 1288Obtains the list of attributes of alarm alert tones. This API uses a promise to return the result. 1289 1290**System API**: This is a system API. 1291 1292**System capability**: SystemCapability.Multimedia.SystemSound.Core 1293 1294**Parameters** 1295 1296| Name | Type | Mandatory| Description | 1297| -------- |--------------| ---- | --------------------------- | 1298| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Application context. | 1299 1300**Return value** 1301 1302| Type | Description | 1303|----------------------------------------------------|----------------------| 1304| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise used to return an array of the attributes of the alarm alert tones.| 1305 1306**Error codes** 1307 1308For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1309 1310| ID| Error Message | 1311| ------- | --------------------- | 1312| 202 | Caller is not a system application. | 1313| 401 | The parameters check failed. | 1314| 5400103 | I/O error. | 1315 1316**Example** 1317 1318```ts 1319import { BusinessError } from '@kit.BasicServicesKit'; 1320import { common } from '@kit.AbilityKit'; 1321 1322let context: common.BaseContext = getContext(this); 1323 1324let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1325systemSoundManagerInstance.getAlarmToneAttrList(context).then((value: systemSoundManager.ToneAttrsArray) => { 1326 console.info(`Promise returned to indicate that the value of the attribute list of alarm tone is obtained.`); 1327}).catch ((err: BusinessError) => { 1328 console.error(`Failed to get the attribute list of alarm tone ${err}`); 1329}); 1330``` 1331 1332### openAlarmTone<sup>12+</sup> 1333 1334openAlarmTone(context: Context, uri: string): Promise<number> 1335 1336Enables an alarm alert tone. This API uses a promise to return the result. 1337 1338**System API**: This is a system API. 1339 1340**System capability**: SystemCapability.Multimedia.SystemSound.Core 1341 1342**Parameters** 1343 1344| Name | Type | Mandatory| Description | 1345| -------- | ---------| ---- |-------------------------------------------------------------------------------------| 1346| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1347| uri | string | Yes | URI of the alarm alert tone. For details, see [media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9).| 1348 1349**Return value** 1350 1351| Type | Description | 1352|-----------------------|----------------| 1353| Promise<number> | Promise used to return the FD.| 1354 1355**Error codes** 1356 1357For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1358 1359| ID| Error Message | 1360| ------- | --------------------- | 1361| 202 | Caller is not a system application. | 1362| 401 | The parameters check failed. | 1363| 5400103 | I/O error. | 1364| 20700001 | Tone type mismatch, e.g. tone of uri is notification instead of alarm. | 1365 1366**Example** 1367 1368```ts 1369import { BusinessError } from '@kit.BasicServicesKit'; 1370import { common } from '@kit.AbilityKit'; 1371 1372let context: Context = getContext(this); 1373let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 1374 1375let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1376systemSoundManagerInstance.openAlarmTone(context, uri).then((value: number) => { 1377 console.info(`Promise returned to indicate the value of fd.`); 1378}).catch ((err: BusinessError) => { 1379 console.error(`Failed to open alarm tone ${err}`); 1380}); 1381``` 1382 1383### close<sup>12+</sup> 1384 1385close(fd: number): Promise<void> 1386 1387Disables an alarm alert tone. This API uses a promise to return the result. 1388 1389**System API**: This is a system API. 1390 1391**System capability**: SystemCapability.Multimedia.SystemSound.Core 1392 1393**Parameters** 1394 1395| Name| Type | Mandatory| Description | 1396|-----| --------| ---- |----------------------------------------------| 1397| fd | number | Yes | File descriptor, which is obtained through [openAlarmTone](#openalarmtone12).| 1398 1399**Return value** 1400 1401| Type | Description | 1402|---------------------|----------------| 1403| Promise<void> | Promise used to return the result.| 1404 1405**Error codes** 1406 1407For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1408 1409| ID| Error Message | 1410| ------- | --------------------- | 1411| 202 | Caller is not a system application. | 1412| 401 | The parameters check failed. | 1413| 5400103 | I/O error. | 1414 1415**Example** 1416 1417```ts 1418import { BusinessError } from '@kit.BasicServicesKit'; 1419import { common } from '@kit.AbilityKit'; 1420 1421let context: Context = getContext(this); 1422let fd = 50; // Use the FD of the target alarm alert tone. 1423 1424let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1425systemSoundManagerInstance.close(fd).then(() => { 1426 console.info(`Promise returned to indicate that the fd has been close.`); 1427}).catch ((err: BusinessError) => { 1428 console.error(`Failed to close fd ${err}`); 1429}); 1430``` 1431 1432### addCustomizedTone<sup>12+</sup> 1433 1434addCustomizedTone(context: BaseContext, toneAttr: ToneAttrs, externalUri: string): Promise<string> 1435 1436Adds a customized tone with a given URI to the tone library. This API uses a promise to return the result. 1437 1438**System API**: This is a system API. 1439 1440**System capability**: SystemCapability.Multimedia.SystemSound.Core 1441 1442**Parameters** 1443 1444| Name| Type | Mandatory| Description | 1445|-----|-----------| ---- |---------------| 1446| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1447| toneAttr | ToneAttrs | Yes | Attributes of the tone. | 1448| externalUri | string | Yes | URI of the tone in the external storage device.| 1449 1450**Return value** 1451 1452| Type | Description | 1453|-----------------------|-------------------------| 1454| Promise<string> | Promise used to return the URI of the tone in the tone library.| 1455 1456**Error codes** 1457 1458For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1459 1460| ID | Error Message | 1461|---------| -------------------- | 1462| 201 | Permission denied. | 1463| 202 | Caller is not a system application. | 1464| 401 | The parameters check failed. | 1465| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1466| 5400103 | I/O error. | 1467 1468**Example** 1469 1470```ts 1471import { BusinessError } from '@kit.BasicServicesKit'; 1472import { common } from '@kit.AbilityKit'; 1473 1474let context: Context = getContext(this); 1475let title = 'test'; // Set the title of the target tone. 1476let fileName = 'displayName_test'; // Set the file name of the target tone. 1477let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; 1478 1479let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 1480toneAttrs.setTitle(title); 1481toneAttrs.setFileName(fileName); 1482toneAttrs.setCategory(categoryValue); 1483 1484let path = 'file://data/test.ogg'; // Set the URI of the target tone. 1485 1486let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1487systemSoundManagerInstance.addCustomizedTone(context, toneAttrs, path).then((value: string) => { 1488 console.info(`Promise returned to indicate that the value of tone uri in ringtone library.`); 1489}).catch ((err: BusinessError) => { 1490 console.error(`Failed to add customized tone ${err}`); 1491}); 1492``` 1493 1494### addCustomizedTone<sup>12+</sup> 1495 1496addCustomizedTone(context: BaseContext, toneAttr: ToneAttrs, fd: number, offset?: number, length?: number): Promise<string> 1497 1498Adds a customized tone with a given FD to the tone library. This API uses a promise to return the result. 1499 1500**System API**: This is a system API. 1501 1502**System capability**: SystemCapability.Multimedia.SystemSound.Core 1503 1504**Parameters** 1505 1506| Name| Type | Mandatory| Description | 1507|-----|-----------|----|------------------------------------------------------------------------| 1508| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1509| toneAttr | [ToneAttrs](#toneattrs12) | Yes | Attributes of the tone. | 1510| fd | number | Yes | File descriptor, which is obtained by calling [fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen).| 1511| offset | number | No | Offset from which the data is read, in bytes. The default value is **0**. | 1512| 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. | 1513 1514**Return value** 1515 1516| Type | Description | 1517|-----------------------|-------------------------| 1518| Promise<string> | Promise used to return the URI of the tone in the tone library.| 1519 1520**Error codes** 1521 1522For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1523 1524| ID | Error Message | 1525|---------| -------------------- | 1526| 201 | Permission denied. | 1527| 202 | Caller is not a system application. | 1528| 401 | The parameters check failed. | 1529| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1530| 5400103 | I/O error. | 1531 1532**Example** 1533 1534```ts 1535import { BusinessError } from '@kit.BasicServicesKit'; 1536import { common } from '@kit.AbilityKit'; 1537 1538let context: Context = getContext(this); 1539let title = 'test'; // Set the title of the target tone. 1540let fileName = 'displayName_test'; // Set the file name of the target tone. 1541let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; 1542 1543let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 1544toneAttrs.setTitle(title); 1545toneAttrs.setFileName(fileName); 1546toneAttrs.setCategory(categoryValue); 1547 1548let fd = 10; // Set the FD of the target tone. 1549let offset = 0; // Set the offset. 1550let length = 50; // Set the data length. 1551 1552let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1553systemSoundManagerInstance.addCustomizedTone(context, toneAttrs, fd, offset, length).then((value: string) => { 1554 console.info(`Promise returned to indicate that the value of tone uri in ringtone library.`); 1555}).catch ((err: BusinessError) => { 1556 console.error(`Failed to add customized tone ${err}`); 1557}); 1558``` 1559 1560### removeCustomizedTone<sup>12+</sup> 1561 1562removeCustomizedTone(context: BaseContext, uri: string): Promise<void> 1563 1564Removes a custom tone from the one library. This API uses a promise to return the result. 1565 1566**System API**: This is a system API. 1567 1568**System capability**: SystemCapability.Multimedia.SystemSound.Core 1569 1570**Parameters** 1571 1572| Name| Type | Mandatory| Description | 1573|-----|-----------| ---- |---------------------------------------------------------------------------------------------------------| 1574| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context. | 1575| uri | string | Yes | Tone URI, which is obtained by using [addCustomizedTone](#addcustomizedtone12) or [getAlarmToneAttrList](#getalarmtoneattrlist12).| 1576 1577**Return value** 1578 1579| Type | Description | 1580|---------------------|-----------------------| 1581| Promise<void> | Promise used to return the result.| 1582 1583**Error codes** 1584 1585For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 1586 1587| ID | Error Message | 1588|---------| -------------------- | 1589| 201 | Permission denied. | 1590| 202 | Caller is not a system application. | 1591| 401 | The parameters check failed. | 1592| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1593| 5400103 | I/O error. | 1594 1595**Example** 1596 1597```ts 1598import { BusinessError } from '@kit.BasicServicesKit'; 1599import { common } from '@kit.AbilityKit'; 1600 1601let context: Context = getContext(this); 1602let uri = 'file://data/test.wav'; // Set the URI of the target tone file. 1603 1604let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1605systemSoundManagerInstance.removeCustomizedTone(context, uri).then(() => { 1606 console.info(`Promise returned to indicate that the customized tone has been deleted.`); 1607}).catch ((err: BusinessError) => { 1608 console.error(`Failed to delete customized tone ${err}`); 1609}); 1610``` 1611 1612## RingtonePlayer<sup>10+</sup> 1613 1614type RingtonePlayer = _RingtonePlayer; 1615 1616Defines a system ringtone player. 1617 1618**System capability**: SystemCapability.Multimedia.SystemSound.Core 1619 1620| Type |Description | 1621|-----------------|-------| 1622| _RingtonePlayer | System ringtone player.| 1623 1624## SystemTonePlayer<sup>11+</sup> 1625 1626type SystemTonePlayer = _SystemTonePlayer; 1627 1628Defines a system alert tone player. 1629 1630**System capability**: SystemCapability.Multimedia.SystemSound.Core 1631 1632| Type | Description | 1633|-----------------|-----------| 1634| _SystemTonePlayer | System alert tone player.| 1635 1636## RingtoneOptions<sup>10+</sup> 1637 1638type RingtoneOptions = _RingtoneOptions; 1639 1640Defines the configuration of a system ringtone player. 1641 1642**System capability**: SystemCapability.Multimedia.SystemSound.Core 1643 1644| Type | Description | 1645|-----------------|-------------| 1646| _RingtoneOptions | Configuration of a system ringtone player.| 1647 1648## SystemToneOptions<sup>11+</sup> 1649 1650type SystemToneOptions = _SystemToneOptions; 1651 1652Defines the configuration of a system alert tone player. 1653 1654**System capability**: SystemCapability.Multimedia.SystemSound.Core 1655 1656| Type | Description | 1657|-----------------|---------------| 1658| _SystemToneOptions | Configuration of a system alert tone player.| 1659