2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__
19 #define __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__
23 * @file sound_manager_doc.h
24 * @brief This file contains high level documentation of the Sound Manager API.
28 * @ingroup CAPI_MEDIA_FRAMEWORK
29 * @defgroup CAPI_MEDIA_SOUND_MANAGER_MODULE Sound Manager
30 * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API provides functions to get and set sound parameters like volume, stream policy and devices.
32 * @section CAPI_MEDIA_SOUND_MANAGER_MODULE_HEADER Required Header
33 * \#include <sound_manager.h>
35 * @section CAPI_MEDIA_SOUND_MANAGER_OVERVIEW Overview
36 * The Sound Manager service allows APIs to manage audio output.
38 * The Sound Manager API allows you to:
39 * - check/control output volumes
40 * - handle a volume changed notification
41 * - determine/control a sound stream policy
42 * - handle the notification of a sound focus status change
43 * - query the basic information of connected sound devices
44 * - handle the notification for connection of a sound device
46 * @subsection CAPI_MEDIA_SOUND_MANAGER_LIFE_CYCLE_ASYNCHRONOUS_OPERATIONS Asynchronous operations
47 * The Sound Manager API allows only asynchronous operations. \n
48 * Thus the result will be passed to the application via the callback mechanism.
49 * An appropriate callback can be called in response to changes initiated from outside the application. \n
50 * Possible callbacks are listed below:
53 * <li> sound_manager_volume_changed_cb() - invoked when volume level is changed.<p></li>
54 * <li> sound_stream_focus_state_changed_cb() - invoked when the state of focus that belongs to the stream_info is changed.<p></li>
55 * <li> sound_stream_focus_state_watch_cb() - invoked when the focus state for each sound stream type is changed.<p></li>
56 * <li> sound_device_connection_changed_cb() - invoked when the connection of a sound device is changed.<p></li>
59 * @subsection CAPI_MEDIA_SOUND_MANAGER_MODULE_LIFE_CYCLE_CALLBACK_OPERATIONS Callback(Event) Operations
60 * The callback mechanism is used to notify the application about significant sound manager events.
61 * <div><table class="doxtable" >
63 * <th><b> REGISTER</b></th>
64 * <th><b> UNREGISTER</b></th>
65 * <th><b> CALLBACK</b></th>
66 * <th><b> DESCRIPTION</b></th>
69 * <td> sound_manager_add_volume_changed_cb()</td>
70 * <td> sound_manager_remove_volume_changed_cb()</td>
71 * <td> sound_manager_volume_changed_cb()</td>
72 * <td> This callback is called when volume value is changed.</td>
75 * <td> sound_manager_create_stream_information()</td>
76 * <td> sound_manager_destroy_stream_information()</td>
77 * <td> sound_stream_focus_state_changed_cb()</td>
78 * <td> This callback is called when the state of focus that belongs to the stream_info is changed.</td>
81 * <td> sound_manager_add_focus_state_watch_cb()</td>
82 * <td> sound_manager_remove_focus_state_watch_cb()</td>
83 * <td> sound_stream_focus_state_watch_cb()</td>
84 * <td> This callback is called when the focus state for each sound stream type is changed regardless of the process.</td>
87 * <td> sound_manager_add_device_connection_changed_cb()</td>
88 * <td> sound_manager_remove_device_connection_changed_cb()</td>
89 * <td> sound_device_connection_changed_cb()</td>
90 * <td> This callback is called when the connection of a sound device is changed.</td>
97 * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
98 * @defgroup CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE Volume
99 * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE API provides functions to check and control volumes.
100 * @section CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE_HEADER Required Header
101 * \#include <sound_manager.h>
103 * @section CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE_OVERVIEW Overview
104 * The Sound Manager Volume API allows you to:
105 * - check/control output volumes
106 * - handle a volume changed notification
108 * The Sound Manager has predefined types of sounds.(system, notification, alarm, ringtone, media, call, voip, voice).
110 * Current volume level of each type can be checked with sound_manager_get_volume().
111 * To get the maximum supported volume level of each type, call sound_manager_get_max_volume().
112 * The volume level of each type can be adjusted with sound_manager_set_volume().
114 * The type of currently playing sound may be obtained by calling sound_manager_get_current_sound_type().
120 * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
121 * @defgroup CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE Stream Policy
122 * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE API provides functions to control a sound stream.
123 * @section CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE_HEADER Required Header
124 * \#include <sound_manager.h>
126 * @section CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE_OVERVIEW Overview
127 * The Sound Manager Stream API allows you to:
128 * - determine/control a sound stream policy
129 * - handle the notification of a sound focus status change
131 * The Sound Manager has predefined sound stream types (media, system, alarm, notification, emergency, voip, etc)
136 * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
137 * @defgroup CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE Device
138 * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE API provides functions to query the information of sound devices.
139 * @section CAPI_MEDIA_SOUND_MANAGER_DEIVCE_MODULE_HEADER Required Header
140 * \#include <sound_manager.h>
142 * @section CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE_OVERVIEW Overview
143 * The Sound Manager Device API allows you to:
144 * - query the basic information of connected sound devices.
145 * - handle the sound device's connection state change notification.
147 * The list of currently connected sound device can be obtained by calling sound_manager_get_device_list().
148 * To get the handle of each sound device, call sound_manager_get_next_device() and sound_manager_get_prev_device().
150 * Device information, such as "type", "IO direction", "ID", "name", can be obtained by calling corresponding APIs.
155 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__ */