4 * Copyright (c) 2015 - 2016 Samsung Electronics Co., Ltd. All rights reserved.
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
20 #ifndef footizenaudiofoo
21 #define footizenaudiofoo
24 #include <hal/hal-audio-interface.h>
28 * @brief This file contains the Audio Hardware Abstraction Layer Interfaces.
32 * @addtogroup TIZEN_AUDIO_HAL_MODULE
37 * @brief Initializes audio hal.
39 * @param[out] audio_handle The audio hal handle
41 * @return @c 0 on success,
42 * otherwise a negative error value
43 * @retval #AUDIO_RET_OK Success
46 audio_return_e audio_init(void **audio_handle);
49 * @brief De-initializes audio hal.
51 * @param[in] audio_handle The audio hal handle
53 * @return @c 0 on success,
54 * otherwise a negative error value
55 * @retval #AUDIO_RET_OK Success
58 audio_return_e audio_deinit(void *audio_handle);
61 * @brief Gets the maximum volume level supported for a particular volume information.
63 * @param[in] audio_handle The audio hal handle
64 * @param[in] info The audio volume information
65 * @param[out] level The maximum volume level
67 * @return @c 0 on success,
68 * otherwise a negative error value
69 * @retval #AUDIO_RET_OK Success
70 * @see audio_set_volume_level()
71 * @see audio_get_volume_level()
72 * @see audio_get_volume_value()
74 audio_return_e audio_get_volume_level_max(void *audio_handle, audio_volume_info_s *info, uint32_t *level);
77 * @brief Gets the volume level specified for a particular volume information.
79 * @param[in] audio_handle The audio hal handle
80 * @param[in] info The audio volume information
81 * @param[out] level The current volume level
83 * @return @c 0 on success,
84 * otherwise a negative error value
85 * @retval #AUDIO_RET_OK Success
86 * @see audio_set_volume_level()
87 * @see audio_get_volume_level_max()
88 * @see audio_get_volume_value()
90 audio_return_e audio_get_volume_level(void *audio_handle, audio_volume_info_s *info, uint32_t *level);
93 * @brief Sets the volume level specified for a particular volume information.
95 * @param[in] audio_handle The audio hal handle
96 * @param[in] info The audio volume information
97 * @param[in] level The volume level to be set
99 * @return @c 0 on success,
100 * otherwise a negative error value
101 * @retval #AUDIO_RET_OK Success
102 * @see audio_get_volume_level()
103 * @see audio_get_volume_level_max()
104 * @see audio_get_volume_value()
106 audio_return_e audio_set_volume_level(void *audio_handle, audio_volume_info_s *info, uint32_t level);
109 * @brief Gets the volume value specified for a particular volume information and level.
111 * @param[in] audio_handle The audio hal handle
112 * @param[in] info The audio volume information
113 * @param[in] level The volume level
114 * @param[out] value The volume value (range is from 0.0 to 1.0 inclusive, 1.0 = 100%)
116 * @return @c 0 on success,
117 * otherwise a negative error value
118 * @retval #AUDIO_RET_OK Success
119 * @see audio_set_volume_level()
120 * @see audio_get_volume_level()
121 * @see audio_get_volume_level_max()
123 audio_return_e audio_get_volume_value(void *audio_handle, audio_volume_info_s *info, uint32_t level, double *value);
126 * @brief Gets the volume mute specified for a particular volume information.
128 * @param[in] audio_handle The audio hal handle
129 * @param[in] info The audio volume information
130 * @param[out] mute The volume mute state : (@c 0 = unmute, @c 1 = mute)
132 * @return @c 0 on success,
133 * otherwise a negative error value
134 * @retval #AUDIO_RET_OK Success
135 * @see audio_set_volume_mute()
137 audio_return_e audio_get_volume_mute(void *audio_handle, audio_volume_info_s *info, uint32_t *mute);
140 * @brief Sets the volume mute specified for a particular volume information.
142 * @param[in] audio_handle The audio hal handle
143 * @param[in] info The audio volume information
144 * @param[in] mute The volume mute state to be set : (@c 0 = unmute, @c 1 = mute)
146 * @return @c 0 on success,
147 * otherwise a negative error value
148 * @retval #AUDIO_RET_OK Success
149 * @see audio_get_volume_mute()
151 audio_return_e audio_set_volume_mute(void *audio_handle, audio_volume_info_s *info, uint32_t mute);
154 * @brief Sets the volume ratio specified for a particular volume information. (optional)
156 * @param[in] audio_handle The audio hal handle
157 * @param[in] info The audio volume information
158 * @param[in] ratio The volume ratio to be set (Min.:0.0 ~ Max.:1.0, default:1.0)
160 * @return @c 0 on success,
161 * otherwise a negative error value
162 * @retval #AUDIO_RET_OK Success
164 audio_return_e audio_set_volume_ratio(void *audio_handle, audio_stream_info_s *info, double ratio);
167 * @brief Gets notified when a ducking is activated and deactivated.
169 * @param[in] audio_handle The audio hal handle
170 * @param[in] info The ducking information including target role, duration and ratio
171 * @param[in] is_activated The activation state (@c true = activated, @c false = deactivated)
173 * @remarks This information can be used for volume controls.
175 * @return @c 0 on success,
176 * otherwise a negative error value
177 * @retval #AUDIO_RET_OK Success
179 audio_return_e audio_notify_ducking_activation_changed(void *audio_handle, audio_ducking_info_s *info, uint32_t is_activated);
182 * @brief Updates the audio routing according to audio route information.
184 * @param[in] audio_handle The audio hal handle
185 * @param[in] info The audio route information including role and devices
187 * @return @c 0 on success,
188 * otherwise a negative error value
189 * @retval #AUDIO_RET_OK Success
190 * @see audio_update_route_option()
192 audio_return_e audio_update_route(void *audio_handle, audio_route_info_s *info);
195 * @brief Updates audio routing option according to audio route option.
197 * @param[in] audio_handle The audio hal handle
198 * @param[in] option The option that can be used for audio routing including role, name and value
200 * @remarks This option can be used for audio routing.\n
201 * It is recommended to apply this option for routing per each role.
203 * @return @c 0 on success,
204 * otherwise a negative error value
205 * @retval #AUDIO_RET_OK Success
206 * @see audio_update_route()
208 audio_return_e audio_update_route_option(void *audio_handle, audio_route_option_s *option);
211 * @brief Gets notified when a stream is connected and disconnected.
213 * @param[in] audio_handle The audio hal handle
214 * @param[in] info The stream information including role, direction, index
215 * @param[in] is_connected The connection state of this stream (@c true = connected, @c false = disconnected)
217 * @remarks This information can be used for audio routing, volume controls and so on.
219 * @return @c 0 on success,
220 * otherwise a negative error value
221 * @retval #AUDIO_RET_OK Success
223 audio_return_e audio_notify_stream_connection_changed(void *audio_handle, audio_stream_info_s *info, uint32_t is_connected);
226 * @brief Opens a PCM device.
228 * @param[in] audio_handle The audio hal handle
229 * @param[in] card The card of PCM
230 * @param[in] device The device of PCM
231 * @param[in] direction The direction of PCM
232 * @param[in] sample_spec The sample specification
233 * @param[in] period_size The period size
234 * @param[in] periods The periods
235 * @param[out] pcm_handle The PCM handle
237 * @return @c 0 on success,
238 * otherwise a negative error value
239 * @retval #AUDIO_RET_OK Success
240 * @see audio_pcm_close()
242 audio_return_e audio_pcm_open(void *audio_handle, const char *card, const char *device, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods, void **pcm_handle);
245 * @brief Starts a PCM device.
247 * @param[in] audio_handle The audio hal handle
248 * @param[in] pcm_handle The PCM handle to be started
250 * @return @c 0 on success,
251 * otherwise a negative error value
252 * @retval #AUDIO_RET_OK Success
253 * @see audio_pcm_avail()
254 * @see audio_pcm_write()
255 * @see audio_pcm_read()
256 * @see audio_pcm_stop()
257 * @see audio_pcm_recover()
259 audio_return_e audio_pcm_start(void *audio_handle, void *pcm_handle);
262 * @brief Stops a PCM device.
264 * @param[in] audio_handle The audio hal handle
265 * @param[in] pcm_handle The PCM handle to be stopped
267 * @return @c 0 on success,
268 * otherwise a negative error value
269 * @retval #AUDIO_RET_OK Success
270 * @see audio_pcm_start()
272 audio_return_e audio_pcm_stop(void *audio_handle, void *pcm_handle);
275 * @brief Closes a PCM device.
277 * @param[in] audio_handle The audio hal handle
278 * @param[in] pcm_handle The PCM handle to be closed
280 * @return @c 0 on success,
281 * otherwise a negative error value
282 * @retval #AUDIO_RET_OK Success
283 * @see audio_pcm_open()
285 audio_return_e audio_pcm_close(void *audio_handle, void *pcm_handle);
288 * @brief Gets available number of frames.
290 * @param[in] audio_handle The audio hal handle
291 * @param[in] pcm_handle The PCM handle
292 * @param[out] avail The available number of frames
294 * @return @c 0 on success,
295 * otherwise a negative error value
296 * @retval #AUDIO_RET_OK Success
297 * @see audio_pcm_write()
298 * @see audio_pcm_read()
300 audio_return_e audio_pcm_avail(void *audio_handle, void *pcm_handle, uint32_t *avail);
303 * @brief Writes frames to a PCM device.
305 * @param[in] audio_handle The audio hal handle
306 * @param[in] pcm_handle The PCM handle
307 * @param[in] buffer The buffer containing frames
308 * @param[in] frames The number of frames to be written
310 * @return @c 0 on success,
311 * otherwise a negative error value
312 * @retval #AUDIO_RET_OK Success
313 * @see audio_pcm_avail()
314 * @see audio_pcm_recover()
316 audio_return_e audio_pcm_write(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
319 * @brief Reads frames from a PCM device.
321 * @param[in] audio_handle The audio hal handle
322 * @param[in] pcm_handle The PCM handle
323 * @param[out] buffer The buffer containing frames
324 * @param[in] frames The number of frames to be read
326 * @return @c 0 on success,
327 * otherwise a negative error value
328 * @retval #AUDIO_RET_OK Success
329 * @see audio_pcm_avail()
330 * @see audio_pcm_recover()
332 audio_return_e audio_pcm_read(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
335 * @brief Gets poll descriptor for a PCM handle.
337 * @param[in] audio_handle The audio hal handle
338 * @param[in] pcm_handle The PCM handle
339 * @param[out] fd The poll descriptor
341 * @return @c 0 on success,
342 * otherwise a negative error value
343 * @retval #AUDIO_RET_OK Success
344 * @see audio_pcm_open()
345 * @see audio_pcm_recover()
347 audio_return_e audio_pcm_get_fd(void *audio_handle, void *pcm_handle, int *fd);
350 * @brief Recovers the PCM state.
352 * @param[in] audio_handle The audio hal handle
353 * @param[in] pcm_handle The PCM handle
354 * @param[in] revents The returned event from pollfd
356 * @return @c 0 on success,
357 * otherwise a negative error value
358 * @retval #AUDIO_RET_OK Success
359 * @see audio_pcm_start()
360 * @see audio_pcm_write()
361 * @see audio_pcm_read()
362 * @see audio_pcm_get_fd()
364 audio_return_e audio_pcm_recover(void *audio_handle, void *pcm_handle, int revents);
367 * @brief Gets parameters of a PCM device.
369 * @param[in] audio_handle The audio hal handle
370 * @param[in] pcm_handle The PCM handle
371 * @param[in] direction The direction of PCM
372 * @param[out] sample_spec The sample specification
373 * @param[out] period_size The period size
374 * @param[out] periods The periods
376 * @return @c 0 on success,
377 * otherwise a negative error value
378 * @retval #AUDIO_RET_OK Success
379 * @see audio_pcm_set_params()
381 audio_return_e audio_pcm_get_params(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t *period_size, uint32_t *periods);
384 * @brief Sets hardware and software parameters of a PCM device.
386 * @param[in] audio_handle The audio hal handle
387 * @param[in] pcm_handle The PCM handle
388 * @param[in] direction The direction of PCM
389 * @param[in] sample_spec The sample specification
390 * @param[in] period_size The period size
391 * @param[in] periods The periods
393 * @return @c 0 on success,
394 * otherwise a negative error value
395 * @retval #AUDIO_RET_OK Success
396 * @see audio_pcm_set_params()
398 audio_return_e audio_pcm_set_params(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
401 * @brief Adds the message callback function.
403 * @param[in] audio_handle The audio hal handle
404 * @param[in] message_cb The message callback function
405 * @param[in] user_data The user data passed to the callback function
408 * @see audio_remove_message_cb()
410 audio_return_e audio_add_message_cb(void *audio_handle, message_cb callback, void *user_data);
413 * @brief Removes the message callback function.
415 * @param[in] audio_handle The audio hal handle
416 * @param[in] message_cb The message callback function to be removed
419 * @see audio_add_message_cb()
421 audio_return_e audio_remove_message_cb(void *audio_handle, message_cb callback);