1 /*
2  * Copyright (c) 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 #ifndef SYSTEM_TONE_PLAYER_H
17 #define SYSTEM_TONE_PLAYER_H
18 
19 #include <string>
20 
21 #include "audio_info.h"
22 
23 namespace OHOS {
24 namespace Media {
25 struct SystemToneOptions {
26     bool muteAudio;
27     bool muteHaptics;
28 };
29 
30 enum class SystemToneState {
31     /** INVALID state */
32     STATE_INVALID = -1,
33     /** Create New instance */
34     STATE_NEW,
35     /** Prepared state */
36     STATE_PREPARED,
37     /** Running state */
38     STATE_RUNNING,
39     /** Stopped state */
40     STATE_STOPPED,
41     /** Released state */
42     STATE_RELEASED,
43     /** Paused state */
44     STATE_PAUSED
45 };
46 
47 enum ToneHapticsFeature : int32_t {
48     STANDARD = 0,
49     GENTLE,
50 };
51 
52 #define SYS_TONE_PLAYER_MAX_VOLUME 1.0f
53 
54 class SystemTonePlayer {
55 public:
56     virtual ~SystemTonePlayer() = default;
57 
58     /**
59      * @brief Returns the title of the system tone uri set.
60      *
61      * @return Returns title as string if the title is obtained successfully.
62      * returns an empty string otherwise.
63      * @since 11
64      */
65     virtual std::string GetTitle() const = 0;
66 
67     /**
68      * @brief Prepare the system tone player.
69      *
70      * @return Returns {@link MSERR_OK} if prepare successfully;
71      * returns an error code defined in {@link media_errors.h} otherwise.
72      * @since 11
73      */
74     virtual int32_t Prepare() = 0;
75 
76     /**
77      * @brief Start playing system tone
78      *
79      * @return Returns a non-zero streamID if successful, zero if it fails.
80      * @since 11
81      */
82     virtual int32_t Start() = 0;
83 
84     /**
85      * @brief Start playing system tone with SystemToneOptions
86      *
87      * @param soundID Indicates the sound ID returned by sound pool.
88      * @param systemToneOptions Indicates the mute status of audio and haptic.
89      * @return Returns a non-zero streamID if successful, zero if it fails.
90      * @since 11
91      */
92     virtual int32_t Start(const SystemToneOptions &systemToneOptions) = 0;
93 
94     /**
95      * @brief Stop playing system tone
96      *
97      * @param streamID Indicates the streamID returned by the Start() or Start(SystemToneOptions systemToneOptions).
98      * @return Returns {@link MSERR_OK} if stop playing system tone successfully;
99      * returns an error code defined in {@link media_errors.h} otherwise.
100      * @since 11
101      */
102     virtual int32_t Stop(const int32_t &streamID) = 0;
103 
104     /**
105      * @brief Releases the system tone client resources
106      *
107      * @return Returns {@link MSERR_OK} if the looping parameter is set successfully to player;
108      * returns an error code defined in {@link media_errors.h} otherwise.
109      * @since 11
110      */
111     virtual int32_t Release() = 0;
112 
113     /**
114      * @brief Set audio volume to the system tone
115      *
116      * @param volume Audio volume value
117      * @return Returns {@link MSERR_OK} if the audio volume is set successfully to player;
118      * returns an error code defined in {@link media_errors.h} otherwise.
119      * @since 12
120      */
121     virtual int32_t SetAudioVolume(float volume) = 0;
122 
123     /**
124      * @brief Get audio volume from the system tone
125      *
126      * @param volume Recevie Audio volume value
127      * @return Returns {@link MSERR_OK} if the audio volume is get successfully from player;
128      * returns an error code defined in {@link media_errors.h} otherwise.
129      * @since 12
130      */
131     virtual int32_t GetAudioVolume(float &recvValue) = 0;
132 
133     /**
134      * @brief Get all supported haptics features
135      *
136      * @param volume Recevie all supported haptics features
137      * @return Returns {@link MSERR_OK} if the  all supported haptics features is get successfully from player;
138      * returns an error code defined in {@link media_errors.h} otherwise.
139      * @since 12
140      */
141     virtual int32_t GetSupportHapticsFeatures(std::vector<ToneHapticsFeature> &recvFeatures) = 0;
142 
143     /**
144      * @brief Set haptics feature to the system tone
145      *
146      * @param volume Haptics feature value
147      * @return Returns {@link MSERR_OK} if the haptics feature is set successfully to player;
148      * returns an error code defined in {@link media_errors.h} otherwise.
149      * @since 12
150      */
151     virtual int32_t SetHapticsFeature(ToneHapticsFeature feature) = 0;
152 
153     /**
154      * @brief Get haptics feature from the system tone
155      *
156      * @param volume Receive haptics feature value
157      * @return Returns {@link MSERR_OK} if the haptics feature is get successfully to player;
158      * returns an error code defined in {@link media_errors.h} otherwise.
159      * @since 12
160      */
161     virtual int32_t GetHapticsFeature(ToneHapticsFeature &feature) = 0;
162 };
163 } // namespace Media
164 } // namespace OHOS
165 #endif // SYSTEM_TONE_PLAYER_H
166