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
27 * @brief This file contains the Audio Hardware Abstraction Layer Interfaces.
31 * @addtogroup TIZEN_AUDIO_HAL_MODULE
36 * @brief Enumeration for return codes.
39 typedef enum audio_return {
41 AUDIO_ERR_UNDEFINED = (int32_t)0x80001000,
42 AUDIO_ERR_RESOURCE = (int32_t)0x80001001,
43 AUDIO_ERR_PARAMETER = (int32_t)0x80001002,
44 AUDIO_ERR_IOCTL = (int32_t)0x80001003,
45 AUDIO_ERR_INVALID_STATE = (int32_t)0x80001004,
46 AUDIO_ERR_INTERNAL = (int32_t)0x80001005,
47 /* add new enemerator here */
48 AUDIO_ERR_NOT_IMPLEMENTED = (int32_t)0x80001100,
52 * @brief Enumeration for audio direction.
55 typedef enum audio_direction {
56 AUDIO_DIRECTION_IN, /**< Capture */
57 AUDIO_DIRECTION_OUT, /**< Playback */
61 * @brief Device information including type, direction and id.
64 typedef struct device_info {
71 * @brief Volume information including type, gain and direction.
74 typedef struct audio_volume_info {
78 } audio_volume_info_t ;
81 * @brief Route information including role and device.
84 typedef struct audio_route_info {
86 device_info_t *device_infos;
87 uint32_t num_of_devices;
91 * @brief Route option including role, name and value.
94 typedef struct audio_route_option {
98 } audio_route_option_t;
101 * @brief Stream information including role, direction and index.
104 typedef struct audio_stream_info {
108 } audio_stream_info_t ;
111 * @brief Called when audio hal implementation needs to send a message.
113 * @param[in] name The message name
114 * @param[in] value The message value
115 * @param[in] user_data The user data passed from the callback registration function
117 * @see audio_add_message_cb()
118 * @see audio_remove_message_cb()
120 typedef void (*message_cb)(const char *name, int value, void *user_data);
123 typedef struct audio_interface {
124 /* Initialization & de-initialization */
125 audio_return_t (*init)(void **audio_handle);
126 audio_return_t (*deinit)(void *audio_handle);
128 audio_return_t (*get_volume_level_max)(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
129 audio_return_t (*get_volume_level)(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
130 audio_return_t (*set_volume_level)(void *audio_handle, audio_volume_info_t *info, uint32_t level);
131 audio_return_t (*get_volume_value)(void *audio_handle, audio_volume_info_t *info, uint32_t level, double *value);
132 audio_return_t (*get_volume_mute)(void *audio_handle, audio_volume_info_t *info, uint32_t *mute);
133 audio_return_t (*set_volume_mute)(void *audio_handle, audio_volume_info_t *info, uint32_t mute);
134 audio_return_t (*set_volume_ratio)(void *audio_handle, audio_stream_info_t *info, double ratio);
136 audio_return_t (*update_route)(void *audio_handle, audio_route_info_t *info);
137 audio_return_t (*update_route_option)(void *audio_handle, audio_route_option_t *option);
139 audio_return_t (*notify_stream_connection_changed)(void *audio_handle, audio_stream_info_t *info, uint32_t is_connected);
141 audio_return_t (*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);
142 audio_return_t (*pcm_start)(void *audio_handle, void *pcm_handle);
143 audio_return_t (*pcm_stop)(void *audio_handle, void *pcm_handle);
144 audio_return_t (*pcm_close)(void *audio_handle, void *pcm_handle);
145 audio_return_t (*pcm_avail)(void *audio_handle, void *pcm_handle, uint32_t *avail);
146 audio_return_t (*pcm_write)(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
147 audio_return_t (*pcm_read)(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
148 audio_return_t (*pcm_get_fd)(void *audio_handle, void *pcm_handle, int *fd);
149 audio_return_t (*pcm_recover)(void *audio_handle, void *pcm_handle, int revents);
150 audio_return_t (*pcm_get_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void **sample_spec, uint32_t *period_size, uint32_t *periods);
151 audio_return_t (*pcm_set_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
152 /* Message callback */
153 audio_return_t (*add_message_cb)(void *audio_handle, message_cb callback, void *user_data);
154 audio_return_t (*remove_message_cb)(void *audio_handle, message_cb callback);
158 * @brief Initializes audio hal.
160 * @param[out] audio_handle The audio hal handle
162 * @return @c 0 on success,
163 * otherwise a negative error value
164 * @retval #AUDIO_RET_OK Success
165 * @see audio_deinit()
167 audio_return_t audio_init(void **audio_handle);
170 * @brief De-initializes audio hal.
172 * @param[in] audio_handle The audio hal handle
174 * @return @c 0 on success,
175 * otherwise a negative error value
176 * @retval #AUDIO_RET_OK Success
179 audio_return_t audio_deinit(void *audio_handle);
182 * @brief Gets the maximum volume level supported for a particular volume information.
184 * @param[in] audio_handle The audio hal handle
185 * @param[in] info The audio volume information
186 * @param[out] level The maximum volume level
188 * @return @c 0 on success,
189 * otherwise a negative error value
190 * @retval #AUDIO_RET_OK Success
191 * @see audio_set_volume_level()
192 * @see audio_get_volume_level()
193 * @see audio_get_volume_value()
195 audio_return_t audio_get_volume_level_max(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
198 * @brief Gets the volume level specified for a particular volume information.
200 * @param[in] audio_handle The audio hal handle
201 * @param[in] info The audio volume information
202 * @param[out] level The current volume level
204 * @return @c 0 on success,
205 * otherwise a negative error value
206 * @retval #AUDIO_RET_OK Success
207 * @see audio_set_volume_level()
208 * @see audio_get_volume_level_max()
209 * @see audio_get_volume_value()
211 audio_return_t audio_get_volume_level(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
214 * @brief Sets the volume level specified for a particular volume information.
216 * @param[in] audio_handle The audio hal handle
217 * @param[in] info The audio volume information
218 * @param[in] level The volume level to be set
220 * @return @c 0 on success,
221 * otherwise a negative error value
222 * @retval #AUDIO_RET_OK Success
223 * @see audio_get_volume_level()
224 * @see audio_get_volume_level_max()
225 * @see audio_get_volume_value()
227 audio_return_t audio_set_volume_level(void *audio_handle, audio_volume_info_t *info, uint32_t level);
230 * @brief Gets the volume value specified for a particular volume information and level.
232 * @param[in] audio_handle The audio hal handle
233 * @param[in] info The audio volume information
234 * @param[in] level The volume level
235 * @param[out] value The volume value (range is from 0.0 to 1.0 inclusive, 1.0 = 100%)
237 * @return @c 0 on success,
238 * otherwise a negative error value
239 * @retval #AUDIO_RET_OK Success
240 * @see audio_set_volume_level()
241 * @see audio_get_volume_level()
242 * @see audio_get_volume_level_max()
244 audio_return_t audio_get_volume_value(void *audio_handle, audio_volume_info_t *info, uint32_t level, double *value);
247 * @brief Gets the volume mute specified for a particular volume information.
249 * @param[in] audio_handle The audio hal handle
250 * @param[in] info The audio volume information
251 * @param[out] mute The volume mute state : (@c 0 = unmute, @c 1 = mute)
253 * @return @c 0 on success,
254 * otherwise a negative error value
255 * @retval #AUDIO_RET_OK Success
256 * @see audio_set_volume_mute()
258 audio_return_t audio_get_volume_mute(void *audio_handle, audio_volume_info_t *info, uint32_t *mute);
261 * @brief Sets the volume mute specified for a particular volume information.
263 * @param[in] audio_handle The audio hal handle
264 * @param[in] info The audio volume information
265 * @param[in] mute The volume mute state to be set : (@c 0 = unmute, @c 1 = mute)
267 * @return @c 0 on success,
268 * otherwise a negative error value
269 * @retval #AUDIO_RET_OK Success
270 * @see audio_get_volume_mute()
272 audio_return_t audio_set_volume_mute(void *audio_handle, audio_volume_info_t *info, uint32_t mute);
275 * @brief Updates the audio routing according to audio route information.
277 * @param[in] audio_handle The audio hal handle
278 * @param[in] info The audio route information including role and devices
280 * @return @c 0 on success,
281 * otherwise a negative error value
282 * @retval #AUDIO_RET_OK Success
283 * @see audio_update_route_option()
285 audio_return_t audio_update_route(void *audio_handle, audio_route_info_t *info);
288 * @brief Updates audio routing option according to audio route option.
290 * @param[in] audio_handle The audio hal handle
291 * @param[in] option The option that can be used for audio routing including role, name and value
293 * @remarks This option can be used for audio routing.\n
294 * It is recommended to apply this option for routing per each role.
296 * @return @c 0 on success,
297 * otherwise a negative error value
298 * @retval #AUDIO_RET_OK Success
299 * @see audio_update_route()
301 audio_return_t audio_update_route_option(void *audio_handle, audio_route_option_t *option);
304 * @brief Gets notified when a stream is connected and disconnected.
306 * @param[in] audio_handle The audio hal handle
307 * @param[in] info The stream information including role, direction, index
308 * @param[in] is_connected The connection state of this stream (@c true = connected, @c false = disconnected)
310 * @remarks This information can be used for audio routing, volume controls and so on.
312 * @return @c 0 on success,
313 * otherwise a negative error value
314 * @retval #AUDIO_RET_OK Success
316 audio_return_t audio_notify_stream_connection_changed(void *audio_handle, audio_stream_info_t *info, uint32_t is_connected);
319 * @brief Opens a PCM device.
321 * @param[in] audio_handle The audio hal handle
322 * @param[in] card The card of PCM
323 * @param[in] device The device of PCM
324 * @param[in] direction The direction of PCM
325 * @param[in] sample_spec The sample specification
326 * @param[in] period_size The period size
327 * @param[in] periods The periods
328 * @param[out] pcm_handle The PCM handle
330 * @return @c 0 on success,
331 * otherwise a negative error value
332 * @retval #AUDIO_RET_OK Success
333 * @see audio_pcm_close()
335 audio_return_t 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);
338 * @brief Starts a PCM device.
340 * @param[in] audio_handle The audio hal handle
341 * @param[in] pcm_handle The PCM handle to be started
343 * @return @c 0 on success,
344 * otherwise a negative error value
345 * @retval #AUDIO_RET_OK Success
346 * @see audio_pcm_avail()
347 * @see audio_pcm_write()
348 * @see audio_pcm_read()
349 * @see audio_pcm_stop()
350 * @see audio_pcm_recover()
352 audio_return_t audio_pcm_start(void *audio_handle, void *pcm_handle);
355 * @brief Stops a PCM device.
357 * @param[in] audio_handle The audio hal handle
358 * @param[in] pcm_handle The PCM handle to be stopped
360 * @return @c 0 on success,
361 * otherwise a negative error value
362 * @retval #AUDIO_RET_OK Success
363 * @see audio_pcm_start()
365 audio_return_t audio_pcm_stop(void *audio_handle, void *pcm_handle);
368 * @brief Closes a PCM device.
370 * @param[in] audio_handle The audio hal handle
371 * @param[in] pcm_handle The PCM handle to be closed
373 * @return @c 0 on success,
374 * otherwise a negative error value
375 * @retval #AUDIO_RET_OK Success
376 * @see audio_pcm_open()
378 audio_return_t audio_pcm_close(void *audio_handle, void *pcm_handle);
381 * @brief Gets available number of frames.
383 * @param[in] audio_handle The audio hal handle
384 * @param[in] pcm_handle The PCM handle
385 * @param[out] avail The available number of frames
387 * @return @c 0 on success,
388 * otherwise a negative error value
389 * @retval #AUDIO_RET_OK Success
390 * @see audio_pcm_write()
391 * @see audio_pcm_read()
393 audio_return_t audio_pcm_avail(void *audio_handle, void *pcm_handle, uint32_t *avail);
396 * @brief Writes frames to a PCM device.
398 * @param[in] audio_handle The audio hal handle
399 * @param[in] pcm_handle The PCM handle
400 * @param[in] buffer The buffer containing frames
401 * @param[in] frames The number of frames to be written
403 * @return @c 0 on success,
404 * otherwise a negative error value
405 * @retval #AUDIO_RET_OK Success
406 * @see audio_pcm_avail()
407 * @see audio_pcm_recover()
409 audio_return_t audio_pcm_write(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
412 * @brief Reads frames from a PCM device.
414 * @param[in] audio_handle The audio hal handle
415 * @param[in] pcm_handle The PCM handle
416 * @param[out] buffer The buffer containing frames
417 * @param[in] frames The number of frames to be read
419 * @return @c 0 on success,
420 * otherwise a negative error value
421 * @retval #AUDIO_RET_OK Success
422 * @see audio_pcm_avail()
423 * @see audio_pcm_recover()
425 audio_return_t audio_pcm_read(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
428 * @brief Gets poll descriptor for a PCM handle.
430 * @param[in] audio_handle The audio hal handle
431 * @param[in] pcm_handle The PCM handle
432 * @param[out] fd The poll descriptor
434 * @return @c 0 on success,
435 * otherwise a negative error value
436 * @retval #AUDIO_RET_OK Success
437 * @see audio_pcm_open()
438 * @see audio_pcm_recover()
440 audio_return_t audio_pcm_get_fd(void *audio_handle, void *pcm_handle, int *fd);
443 * @brief Recovers the PCM state.
445 * @param[in] audio_handle The audio hal handle
446 * @param[in] pcm_handle The PCM handle
447 * @param[in] revents The returned event from pollfd
449 * @return @c 0 on success,
450 * otherwise a negative error value
451 * @retval #AUDIO_RET_OK Success
452 * @see audio_pcm_start()
453 * @see audio_pcm_write()
454 * @see audio_pcm_read()
455 * @see audio_pcm_get_fd()
457 audio_return_t audio_pcm_recover(void *audio_handle, void *pcm_handle, int revents);
460 * @brief Gets parameters of a PCM device.
462 * @param[in] audio_handle The audio hal handle
463 * @param[in] pcm_handle The PCM handle
464 * @param[in] direction The direction of PCM
465 * @param[out] sample_spec The sample specification
466 * @param[out] period_size The period size
467 * @param[out] periods The periods
469 * @return @c 0 on success,
470 * otherwise a negative error value
471 * @retval #AUDIO_RET_OK Success
472 * @see audio_pcm_set_params()
474 audio_return_t audio_pcm_get_params(void *audio_handle, void *pcm_handle, uint32_t direction, void **sample_spec, uint32_t *period_size, uint32_t *periods);
477 * @brief Sets hardware and software parameters of a PCM device.
479 * @param[in] audio_handle The audio hal handle
480 * @param[in] pcm_handle The PCM handle
481 * @param[in] direction The direction of PCM
482 * @param[in] sample_spec The sample specification
483 * @param[in] period_size The period size
484 * @param[in] periods The periods
486 * @return @c 0 on success,
487 * otherwise a negative error value
488 * @retval #AUDIO_RET_OK Success
489 * @see audio_pcm_set_params()
491 audio_return_t audio_pcm_set_params(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
494 * @brief Adds the message callback function.
496 * @param[in] audio_handle The audio hal handle
497 * @param[in] message_cb The message callback function
498 * @param[in] user_data The user data passed to the callback function
501 * @see audio_remove_message_cb()
503 audio_return_t audio_add_message_cb(void *audio_handle, message_cb callback, void *user_data);
506 * @brief Removes the message callback function.
508 * @param[in] audio_handle The audio hal handle
509 * @param[in] message_cb The message callback function to be removed
512 * @see audio_add_message_cb()
514 audio_return_t audio_remove_message_cb(void *audio_handle, message_cb callback);