1/*
2 * Copyright (c) 2023-2023 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @file
18 * @kit AudioKit
19 */
20
21import type systemSoundManager from '../@ohos.multimedia.systemSoundManager';
22
23/**
24 * System tone player object.
25 * @typedef SystemTonePlayer
26 * @syscap SystemCapability.Multimedia.SystemSound.Core
27 * @systemapi
28 * @since 11
29 */
30export interface SystemTonePlayer {
31  /**
32   * Gets the title of system tone.
33   * @returns { Promise<string> } Promise used to return the title.
34   * @throws { BusinessError } 202 - Caller is not a system application.
35   * @throws { BusinessError } 5400103 - I/O error.
36   * @syscap SystemCapability.Multimedia.SystemSound.Core
37   * @systemapi
38   * @since 11
39   */
40  getTitle(): Promise<string>;
41
42  /**
43   * Sets the volume scale of audio.
44   * @param { number } scale - Audio volume scale, should be float in [0,1]
45   * @throws { BusinessError } 202 - Caller is not a system application.
46   * @throws { BusinessError } 401 - Parameter error. Possible causes:
47   *                                 1.Mandatory parameters are left unspecified;
48   *                                 2.Incorrect parameter types.
49   * @throws { BusinessError } 5400102 - Operation not allowed.
50   * @throws { BusinessError } 20700002 - Parameter check error. For example, value is outside [0,1].
51   * @syscap SystemCapability.Multimedia.SystemSound.Core
52   * @systemapi
53   * @since 13
54   */
55  setAudioVolumeScale(scale: number): void;
56
57  /**
58   * Gets the volume scale of audio.
59   * @returns { number } Audio volume scale.
60   * @throws { BusinessError } 202 - Caller is not a system application.
61   * @syscap SystemCapability.Multimedia.SystemSound.Core
62   * @systemapi
63   * @since 13
64   */
65  getAudioVolumeScale(): number;
66
67  /**
68   * Get supported haptics features currently.
69   * @returns { Promise<Array<systemSoundManager.ToneHapticsFeature>> } Promise used to return result of this call.
70   * @throws { BusinessError } 202 - Caller is not a system application.
71   * @throws { BusinessError } 20700003 - Unsupported operation.
72   * @syscap SystemCapability.Multimedia.SystemSound.Core
73   * @systemapi
74   * @since 13
75   */
76  getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>>;
77
78  /**
79   * Set haptic feature that is used when playing.
80   * @param { systemSoundManager.ToneHapticsFeature } hapticsFeature - haptics Feature.
81   * @throws { BusinessError } 202 - Caller is not a system application.
82   * @throws { BusinessError } 401 - Parameter error. Possible causes:
83   *                                 1.Mandatory parameters are left unspecified;
84   *                                 2.Incorrect parameter types.
85   * @throws { BusinessError } 5400102 - Operation not allowed.
86   * @throws { BusinessError } 20700003 - Unsupported operation.
87   * @syscap SystemCapability.Multimedia.SystemSound.Core
88   * @systemapi
89   * @since 13
90   */
91  setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void;
92
93  /**
94   * Get haptic feature that is used when playing.
95   * @returns { systemSoundManager.ToneHapticsFeature } haptics feature that is used when playing.
96   * @throws { BusinessError } 202 - Caller is not a system application.
97   * @throws { BusinessError } 20700003 - Unsupported operation.
98   * @syscap SystemCapability.Multimedia.SystemSound.Core
99   * @systemapi
100   * @since 13
101   */
102  getHapticsFeature(): systemSoundManager.ToneHapticsFeature;
103
104  /**
105   * Prepare to play.
106   * @returns { Promise<void> } Promise used to return result of prepare.
107   * @throws { BusinessError } 202 - Caller is not a system application.
108   * @throws { BusinessError } 5400102 - Operation not allowed.
109   * @throws { BusinessError } 5400103 - I/O error.
110   * @syscap SystemCapability.Multimedia.SystemSound.Core
111   * @systemapi
112   * @since 11
113   */
114  prepare(): Promise<void>;
115
116  /**
117   * Start playing the system tone. By default, the audio and haptic will not be muted. Using tone options to mute audio
118   * or haptics. If haptics is needed, caller should have the permission of ohos.permission.VIBRATE.
119   * @permission ohos.permission.VIBRATE
120   * @param { SystemToneOptions } toneOptions - Tone options used for this play.
121   * @returns { Promise<number> } Promise used to return the id of this playback.
122   * @throws { BusinessError } 201 - Permission denied.
123   * @throws { BusinessError } 202 - Caller is not a system application.
124   * @throws { BusinessError } 401 - Parameter error. Possible causes:
125   *                                 1.Mandatory parameters are left unspecified;
126   *                                 2.Incorrect parameter types.
127   * @throws { BusinessError } 5400102 - Operation not allowed.
128   * @syscap SystemCapability.Multimedia.SystemSound.Core
129   * @systemapi
130   * @since 11
131   */
132  start(toneOptions?: SystemToneOptions): Promise<number>;
133
134  /**
135   * Stop with playback id.
136   * @param { number } id - The Playback id to stop.
137   * @returns { Promise<void> } Promise used to return result of this stop.
138   * @throws { BusinessError } 202 - Caller is not a system application.
139   * @throws { BusinessError } 401 - Parameter error. Possible causes:
140   *                                 1.Mandatory parameters are left unspecified;
141   *                                 2.Incorrect parameter types.
142   * @throws { BusinessError } 5400102 - Operation not allowed.
143   * @syscap SystemCapability.Multimedia.SystemSound.Core
144   * @systemapi
145   * @since 11
146   */
147  stop(id: number): Promise<void>;
148
149  /**
150   * Release this system tone player.
151   * @returns { Promise<void> } Promise used to return result of release.
152   * @throws { BusinessError } 202 - Caller is not a system application.
153   * @syscap SystemCapability.Multimedia.SystemSound.Core
154   * @systemapi
155   * @since 11
156   */
157  release(): Promise<void>;
158}
159
160/**
161 * System tone options used when SystemTonePlayer start playing.
162 * @typedef SystemToneOptions
163 * @syscap SystemCapability.Multimedia.SystemSound.Core
164 * @systemapi
165 * @since 11
166 */
167export interface SystemToneOptions {
168  /**
169   * Mute audio.
170   * @type {?boolean}
171   * @syscap SystemCapability.Multimedia.SystemSound.Core
172   * @systemapi
173   * @since 11
174   */
175  muteAudio?: boolean;
176
177  /**
178   * Mute haptics.
179   * @type {?boolean}
180   * @syscap SystemCapability.Multimedia.SystemSound.Core
181   * @systemapi
182   * @since 11
183   */
184  muteHaptics?: boolean;
185}