Check state before acquiring/releasing focus
[platform/core/api/sound-manager.git] / include / sound_manager_internal_tv.h
1 /*
2 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef __TIZEN_MEDIA_SOUND_MANAGER_INTERNAL_H__
18 #define __TIZEN_MEDIA_SOUND_MANAGER_INTERNAL_H__
19
20 #ifdef __cplusplus
21 extern "C"
22 {
23 #endif
24
25 /**
26  * @file sound_manager_internal.h
27  * @brief This file contains the Sound Manager Internal API.
28  */
29
30 /**
31  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_MODULE
32  * @{
33  */
34
35 #define SOUND_TYPE_NUM                SOUND_TYPE_VOICE + 1
36
37 /**
38  * @internal
39  * @brief Virtual sound stream handle.
40  * @since_tizen 3.0
41  */
42 typedef struct virtual_sound_stream_s* virtual_sound_stream_h;
43
44 /**
45  * @internal
46  * @brief Enumeration for Native API.
47  * @since_tizen 3.0
48  */
49 typedef enum {
50         NATIVE_API_SOUND_MANAGER,   /**< Sound-manager Native API */
51         NATIVE_API_PLAYER,          /**< Player Native API */
52         NATIVE_API_WAV_PLAYER,      /**< Wav-player Native API */
53         NATIVE_API_TONE_PLAYER,     /**< Tone-player Native API */
54         NATIVE_API_AUDIO_IO,        /**< Audio-io Native API */
55         NATIVE_API_RECORDER,        /**< Recorder Native API */
56 } native_api_e;
57
58 /**
59  * @internal
60  * @brief Enumeration for sound stream type for internal.
61  * @since_tizen 3.0
62  */
63 typedef enum {
64         SOUND_STREAM_TYPE_RINGTONE_CALL = 100, /**< Sound stream type for ringtone for call */
65         SOUND_STREAM_TYPE_RINGBACKTONE_CALL,   /**< Sound stream type for ringback tone for call */
66         SOUND_STREAM_TYPE_VOICE_CALL,          /**< Sound stream type for voice-call */
67         SOUND_STREAM_TYPE_VIDEO_CALL,          /**< Sound stream type for video-call */
68         SOUND_STREAM_TYPE_RADIO,               /**< Sound stream type for radio */
69         SOUND_STREAM_TYPE_LOOPBACK,            /**< Sound stream type for loopback */
70         SOUND_STREAM_TYPE_LOOPBACK_MIRRORING,  /**< Sound stream type for loopback-mirroring */
71         SOUND_STREAM_TYPE_SOLO,                /**< Sound stream type for solo */
72 } sound_stream_type_internal_e;
73
74 /**
75  * @internal
76  * @brief Enumeration for sound filters.
77  * @since_tizen 4.0
78  */
79 typedef enum {
80         SOUND_FILTER_NONE = 0,
81         SOUND_FILTER_SOUNDALIVE,
82 } sound_filter_e;
83
84 /**
85  * @internal
86  * @brief Enumeration for filter preset.
87  * @since_tizen 4.0
88  */
89 typedef enum {
90         SOUND_FILTER_PRESET_SOUNDALIVE_NORMAL = 0,   /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
91         SOUND_FILTER_PRESET_SOUNDALIVE_TUBE,         /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
92         SOUND_FILTER_PRESET_SOUNDALIVE_VIRT71,       /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
93         SOUND_FILTER_PRESET_SOUNDALIVE_STUDIO,       /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
94         SOUND_FILTER_PRESET_SOUNDALIVE_CLUB,         /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
95         SOUND_FILTER_PRESET_SOUNDALIVE_CONCERT_HALL, /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
96 } sound_filter_preset_e;
97
98 /**
99  * @internal
100  * @brief Creates a handle for stream information.
101  * @since_tizen 3.0
102  *
103  * @remarks     Do not call this API within sound_stream_focus_state_changed_cb() and sound_stream_focus_state_watch_cb(),\n
104  *      otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
105  *      To apply the stream policy according to this stream information, this handle should be passed to other APIs\n
106  *      related to playback or recording.(e.g. player, wav-player, audio-io, etc.)
107  *
108  * @param[in]   stream_type     The type of stream for internal usage
109  * @param[in]   callback        The focus state change callback function
110  * @param[in]   user_data       The user data to be passed to the callback function
111  * @param[out]  stream_info     The handle of stream information
112  * @return @c 0 on success,
113  *         otherwise a negative error value
114  * @retval #SOUND_MANAGER_ERROR_NONE Success
115  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
116  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
117  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
118  * @see sound_manager_destroy_stream_information()
119  * @see sound_manager_add_device_for_stream_routing()
120  * @see sound_manager_remove_device_for_stream_routing()
121  * @see sound_manager_apply_stream_routing()
122  * @see sound_manager_acquire_focus()
123  * @see sound_manager_destroy_focus()
124  * @see sound_manager_get_focus_state()
125  */
126 int sound_manager_create_stream_information_internal(sound_stream_type_internal_e stream_type, sound_stream_focus_state_changed_cb callback, void *user_data, sound_stream_info_h *stream_info);
127
128 /**
129  * @internal
130  * @brief Sets the stream routing option.
131  * @since_tizen 3.0
132  *
133  * @remarks     If the stream has not been made yet, this setting will be applied when the stream starts to play.
134  *
135  * @param[in]   stream_info     The handle of stream information
136  * @param[in]   name    The name of option
137  * @param[in]   value   The value of option
138  * @return @c 0 on success,
139  *         otherwise a negative error value
140  * @retval #SOUND_MANAGER_ERROR_NONE Success
141  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
142  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
143  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
144  * @pre Call sound_manager_create_stream_information() before calling this function.
145  * @see sound_manager_create_stream_information()
146  * @see sound_manager_create_stream_information_internal()
147  * @see sound_manager_destroy_stream_information()
148  */
149 int sound_manager_set_stream_routing_option(sound_stream_info_h stream_info, const char *name, int value);
150
151 /**
152  * @internal
153  * @brief Queries if this stream information handle is available for the API.
154  * @since_tizen 3.0
155  * @param[in]   stream_info     The handle of stream information
156  * @param[in]   api_name        The native API name
157  * @param[out]  is_available    If @c true the api_name is available, @c false the api_name is not available for this strema_info
158  * @return @c 0 on success,
159  *         otherwise a negative error value
160  * @retval #SOUND_MANAGER_ERROR_NONE Success
161  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
162  * @see sound_manager_create_stream_information()
163  * @see sound_manager_destroy_stream_information()
164  */
165 int sound_manager_is_available_stream_information(sound_stream_info_h stream_info, native_api_e api_name, bool *is_available);
166
167 /**
168  * @internal
169  * @brief Gets stream type from the stream information handle.
170  * @since_tizen 3.0
171  * @param[in]   stream_info     The handle of stream information
172  * @param[out]  type    The stream type
173  * @return @c 0 on success,
174  *         otherwise a negative error value
175  * @retval #SOUND_MANAGER_ERROR_NONE Success
176  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
177  * @see sound_manager_create_stream_information()
178  * @see sound_manager_destroy_stream_information()
179  */
180 int sound_manager_get_type_from_stream_information(sound_stream_info_h stream_info, char **type);
181
182 /**
183  * @internal
184  * @brief Gets the index of the stream information handle.
185  * @since_tizen 3.0
186  * @param[in]   stream_info     The handle of stream information
187  * @param[out]  index   The unique index
188  *
189  * @return @c 0 on success,
190  *         otherwise a negative error value
191  * @retval #SOUND_MANAGER_ERROR_NONE Success
192  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
193  * @see sound_manager_create_stream_information()
194  * @see sound_manager_destroy_stream_information()
195  */
196 int sound_manager_get_index_from_stream_information(sound_stream_info_h stream_info, int *index);
197
198 /**
199  * @internal
200  * @brief Gets the internal stream information handle for VoIP session.
201  * @since_tizen 3.0
202  *
203  * @remarks     If VoIP session is not set in this process, it'll return #SOUND_MANAGER_ERROR_NO_DATA.
204  *
205  * @param[out]  stream_info     The handle of stream information
206  *
207  * @return @c 0 on success,
208  *         otherwise a negative error value
209  * @retval #SOUND_MANAGER_ERROR_NONE Success
210  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
211  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
212  * @see sound_manager_set_session_type()
213  * @see sound_manager_set_voip_session_mode()
214  */
215 int sound_manager_get_internal_voip_stream_information(sound_stream_info_h *stream_info);
216
217 /**
218  * @internal
219  * @brief Disable session backward compatibility.
220  * @since_tizen 3.0
221  *
222  * @remarks     Multimedia framework support backward compatibility of legacy sound session. \n
223  *      If a process does not want legacy sound session behavior in each multimedia framework, \n
224  *      this function can be used explicitly not to support that.
225  *
226  * @return @c 0 on success,
227  *         otherwise a negative error value
228  * @retval #SOUND_MANAGER_ERROR_NONE Success
229  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
230  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
231  */
232 int sound_manager_disable_session_backward_compatibility(void);
233
234 /**
235  * @internal
236  * @brief Creates a virtual stream handle.
237  * @since_tizen 3.0
238  * @param[in]   stream_info     The handle of stream information
239  * @param[out]  virtual_stream  The handle of virtual stream
240  * @return @c 0 on success,
241  *         otherwise a negative error value
242  * @retval #SOUND_MANAGER_ERROR_NONE Success
243  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
244  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
245  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
246  * @see sound_manager_create_stream_information()
247  * @see sound_manager_destroy_stream_information()
248  * @see sound_manager_destroy_virtual_stream()
249  * @see sound_manager_start_virtual_stream()
250  * @see sound_manager_stop_virtual_stream()
251  */
252 int sound_manager_create_virtual_stream(sound_stream_info_h stream_info, virtual_sound_stream_h *virtual_stream);
253
254 /**
255  * @internal
256  * @brief Destroys the virtual stream handle.
257  * @since_tizen 3.0
258  * @param[in]   virtual_stream  The handle of virtual stream
259  * @return @c 0 on success,
260  *         otherwise a negative error value
261  * @retval #SOUND_MANAGER_ERROR_NONE Success
262  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
263  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
264  * @see sound_manager_create_virtual_stream()
265  * @see sound_manager_start_virtual_stream()
266  * @see sound_manager_stop_virtual_stream()
267  */
268 int sound_manager_destroy_virtual_stream(virtual_sound_stream_h virtual_stream);
269
270 /**
271  * @internal
272  * @brief Starts the virtual stream.
273  * @since_tizen 3.0
274  * @param[in]   virtual_stream  The handle of virtual stream
275  * @return @c 0 on success,
276  *         otherwise a negative error value
277  * @retval #SOUND_MANAGER_ERROR_NONE Success
278  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
279  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
280  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
281  * @see sound_manager_create_virtual_stream()
282  * @see sound_manager_destroy_virtual_stream()
283  * @see sound_manager_stop_virtual_stream()
284  */
285 int sound_manager_start_virtual_stream(virtual_sound_stream_h virtual_stream);
286
287 /**
288  * @internal
289  * @brief Stops the virtual stream.
290  * @since_tizen 3.0
291  * @param[in]   virtual_stream  The handle of virtual stream
292  * @return @c 0 on success,
293  *         otherwise a negative error value
294  * @retval #SOUND_MANAGER_ERROR_NONE Success
295  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
296  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
297  * @see sound_manager_create_virtual_stream()
298  * @see sound_manager_destroy_virtual_stream()
299  * @see sound_manager_start_virtual_stream()
300  */
301 int sound_manager_stop_virtual_stream(virtual_sound_stream_h virtual_stream);
302
303 /**
304  * @internal
305  * @brief Set sound filter and apply to audio streams given selected stream type.
306  * @since_tizen 4.0
307  * @param[in]   stream_type             stream type to apply
308  * @param[in]   filter                  sound filter to apply
309  * @return @c 0 on success,
310  *         otherwise a negative error value
311  * @retval #SOUND_MANAGER_ERROR_NONE Success
312  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
313  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
314  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
315  * @see sound_manager_unset_filter()
316  */
317 int sound_manager_set_filter(sound_stream_type_e stream_type, sound_filter_e filter);
318
319 /**
320  * @internal
321  * @brief Unset sound filter and remove from audio streams given selected stream type.
322  * @since_tizen 4.0
323  * @param[in]   stream_type             stream type to remove
324  * @return @c 0 on success,
325  *         otherwise a negative error value
326  * @retval #SOUND_MANAGER_ERROR_NONE Success
327  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
328  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
329  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
330  * @see sound_manager_set_filter()
331  */
332 int sound_manager_unset_filter(sound_stream_type_e stream_type);
333
334 /**
335  * @internal
336  * @brief Apply preset configuration to the filter according to selected stream type.
337  * @since_tizen 4.0
338  * @param[in]   stream_type             given stream type
339  * @param[in]   filter                  given sound filter
340  * @param[in]   preset                  filter preset to apply
341  * @return @c 0 on success,
342  *         otherwise a negative error value
343  * @retval #SOUND_MANAGER_ERROR_NONE Success
344  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
345  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
346  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
347  * @see sound_manager_set_filter()
348  */
349 int sound_manager_set_filter_preset(sound_stream_type_e stream_type, sound_filter_e filter, sound_filter_preset_e preset);
350
351 /**
352  * @}
353  */
354
355 #ifdef __cplusplus
356 }
357 #endif
358
359 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_INTERNAL_H__ */