目录

ringtone (Ringtone Service)

The ringtone module provides the function of setting ringtones.

Since: 5.0.0(12)

Modules to Import

import { ringtone } from '@kit.RingtoneKit';

RingtoneType

Enumeration of ringtone types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Name Value Description
CALL 0 Ringtone for incoming calls.
MESSAGE 1 Ringtone for SMS messages.
NOTIFICATION 2 Ringtone for notifications.
ALARM 3 Ringtone for alarms.

RingtoneErrors

Enumeration of error codes of the APIs for setting ringtones and obtaining supported ringtone types and ringtone file types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Name Value Description
ERROR_INVALID_PARAM 401 Invalid parameter.
ERROR_USER_CANCELED 1011600001 The operation is canceled by the user.
ERROR_FILE_NOT_FOUND 1011600002 The file does not exist.
ERROR_SHOW_FAILED 1011600003 The ringtone dialog box fails to be displayed.
ERROR_CALL_SYSTEM_API_FAILED 1011600004 Failed to call the system API.
ERROR_DATA_TYPE_NOT_MATCHED 1011600005 Unmatched file type. Since: 26.0.0
ERROR_SYSTEM 1011699999 Internal system error.

ringtone.getSupportedRingtoneTypes

getSupportedRingtoneTypes(): Array<RingtoneType>

Queries custom ringtone types supported by the system.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Returns:

Type Description
Array<RingtoneType> Custom ringtone types supported by the system.

Example:

import { ringtone } from '@kit.RingtoneKit';
import { JSON } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('Query Supported Custom Ringtone Types')
          .width(200)
          .height(50)
          .onClick(() => {
            let typeList: ringtone.RingtoneType[] = ringtone.getSupportedRingtoneTypes()
            hilog.info(DOMAIN, APP_TAG, `getSupportedRingtoneTypes: ${JSON.stringify(typeList)}`);
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.getSupportedRingtoneTypes

getSupportedRingtoneTypes(mediaType: uniformTypeDescriptor.UniformDataType): Array<RingtoneType>

Queries custom ringtone types supported by the system.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 26.0.0

Parameters:

Parameter Type Mandatory Description
mediaType uniformTypeDescriptor.UniformDataType Yes File type to be queried.

Returns:

Type Description
Array<RingtoneType> Custom ringtone types supported by the system.

Example:

import { ringtone } from '@kit.RingtoneKit';
import { JSON } from '@kit.ArkTS';
import { uniformTypeDescriptor } from '@kit.ArkData';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('Query Supported Custom Ringtone Types')
          .width(200)
          .height(50)
          .onClick(() => {
            let typeList: ringtone.RingtoneType[] = ringtone.getSupportedRingtoneTypes(uniformTypeDescriptor.UniformDataType.AUDIO)
            hilog.info(DOMAIN, APP_TAG, `getSupportedRingtoneTypes: ${JSON.stringify(typeList)}`);
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.getSupportedDataTypes

getSupportedDataTypes(ringtoneType: RingtoneType): Array<uniformTypeDescriptor.UniformDataType>

Queries the file types supported by a ringtone type.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
ringtoneType RingtoneType Yes Ringtone type to be queried.

Returns:

Type Description
Array<uniformTypeDescriptor.UniformDataType> File types supported by a ringtone type.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes:ringtoneType is invalid.

Example:

import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { uniformTypeDescriptor } from '@kit.ArkData';
import { JSON } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('Query Supported File Types')
          .width(200)
          .height(50)
          .onClick(() => {
            try {
              let typeList: uniformTypeDescriptor.UniformDataType[] =
                ringtone.getSupportedDataTypes(ringtone.RingtoneType.NOTIFICATION)
              hilog.info(DOMAIN, APP_TAG, `getSupportedDataType: ${JSON.stringify(typeList)}`);
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `getSupportedDataType error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.getSupportedMaxDuration

getSupportedMaxDuration(ringtoneType: RingtoneType, dataType: uniformTypeDescriptor.UniformDataType): number

Queries the maximum file duration supported by different ringtone types and file types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
ringtoneType RingtoneType Yes Ringtone type to be queried.
dataType uniformTypeDescriptor.UniformDataType Yes File type to be queried.

Returns:

Type Description
number Maximum duration (unit: second) supported by the ringtone and file types. The maximum duration for an alarm ringtone is 300s, for an SMS message ringtone and notification ringtone is 7s, and for an incoming call ringtone is 60s.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes:data type does not match the ringtone type.

Example:

import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { uniformTypeDescriptor } from '@kit.ArkData';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('Query Maximum Duration')
          .width(200)
          .height(50)
          .onClick(() => {
            try {
              let maxDuration: number =
                ringtone.getSupportedMaxDuration(ringtone.RingtoneType.MESSAGE,
                  uniformTypeDescriptor.UniformDataType.MP3)
              hilog.info(DOMAIN, APP_TAG, `getSupportedMaxDuration: ${maxDuration}`);
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `getSupportedMaxDuration error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.getSupportedMaxSize

getSupportedMaxSize(ringtoneType: RingtoneType, dataType: uniformTypeDescriptor.UniformDataType): number

Queries the maximum file size supported by different ringtone types and file types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 26.0.0

Parameters:

Parameter Type Mandatory Description
ringtoneType RingtoneType Yes Ringtone type to be queried.
dataType uniformTypeDescriptor.UniformDataType Yes File type to be queried.

Returns:

Type Description
number Maximum file size (unit: KB) supported by the ringtone and file types. The maximum size of a video file is 200 MB. If the size of an audio file is not limited, -1 is returned.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

ID Error Message
1011600005 The data type does not match the ringtone type.

Example:

import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { uniformTypeDescriptor } from '@kit.ArkData';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('Query File Size Limit')
          .width(200)
          .height(50)
          .onClick(() => {
            try {
              let maxSize: number =
                ringtone.getSupportedMaxSize(ringtone.RingtoneType.CALL,
                  uniformTypeDescriptor.UniformDataType.MP3)
              hilog.info(DOMAIN, APP_TAG, `getSupportedMaxSize: ${maxSize}`);
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `getSupportedMaxSize error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.startRingtoneSetting

startRingtoneSetting(context: common.UIAbilityContext, path: string, name: string, callback: AsyncCallback<RingtoneType>): void

Opens the ringtone setting pop-up window and returns the type of the tapped ringtone. This API returns the result asynchronously through a callback.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
path string Yes Path of the file on which you have the access permission.
name string Yes File name. The value contains a maximum of 1,000 characters.
callback AsyncCallback<RingtoneType> Yes Callback used to return the ringtone type set by the user.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

ID Error Message
401 Parameter error. Possible causes: context is invalid.
1011600001 User canceled.
1011600002 The media file is not found.
1011600003 Failed to show the dialog box.
1011600004 Failed to call the system API.
1011699999 System exception.

Example:

import { common } from '@kit.AbilityKit';
import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { JSON } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    Stack() {
      Column() {
        Button('Set Ringtone OGG Format')
          .width(200)
          .height(50)
          .onClick(() => {
            let audioPath: string = this.context.filesDir + '/test.ogg'
            let splitList = audioPath.split('/')
            let fileName = splitList[splitList.length - 1]
            hilog.info(DOMAIN, APP_TAG, `audioPath: ${audioPath}`)
            hilog.info(DOMAIN, APP_TAG, `fileName: ${fileName}`)

            try {
              ringtone.startRingtoneSetting(this.context, audioPath, fileName, (err, res) => {
                hilog.info(DOMAIN, APP_TAG, `Return value: ${JSON.stringify(res)}`)
              })
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `accessSync failed with error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.startRingtoneSetting

startRingtoneSetting(context: common.UIAbilityContext, path: string, name: string): Promise<RingtoneType>

Opens the ringtone setting pop-up window and returns the type of the tapped ringtone. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
path string Yes Path of the file on which you have the access permission.
name string Yes File name. The value contains a maximum of 1,000 characters.

Returns:

Type Description
Promise<RingtoneType> Promise used to return the ringtone type set by the user.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

ID Error Message
401 Parameter error. Possible causes: context is invalid.
1011600001 User canceled.
1011600002 The media file is not found.
1011600003 Failed to show the dialog box.
1011600004 Failed to call the system API.
1011699999 System exception.

Example:

import { common } from '@kit.AbilityKit';
import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { JSON } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    Stack() {
      Column() {
        Button('Set Ringtone OGG Format')
          .width(200)
          .height(50)
          .onClick(() => {
            let audioPath: string = this.context.filesDir + '/test.ogg'
            let splitList = audioPath.split('/')
            let fileName = splitList[splitList.length - 1]
            hilog.info(DOMAIN, APP_TAG, `audioPath: ${audioPath}`)
            hilog.info(DOMAIN, APP_TAG, `fileName: ${fileName}`)

            try {
              ringtone.startRingtoneSetting(this.context, audioPath, fileName).then(res => {
                hilog.info(DOMAIN, APP_TAG, `Return value: ${JSON.stringify(res)}`)
              })
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `accessSync failed with error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}