wearable/doc/sound_manager_doc.h

   1 /*
   2  * Copyright (c) 2011 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
  18 #ifndef __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__
  19 #define __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__
  20
  21
  22 /**
  23  * @file sound_manager_doc.h
  24  * @brief This file contains high level documentation of the Sound Manager API.
  25  */
  26
  27 /**
  28  * @defgroup CAPI_MEDIA_SOUND_MANAGER_MODULE Sound Manager
  29  * @brief  The @ref CAPI_MEDIA_SOUND_MANAGER_MODULE  APIs provides functions to get and set sound parameters like volume and route policy.
  30  * @ingroup CAPI_MEDIA_FRAMEWORK
  31  *
  32  * @section CAPI_MEDIA_SOUND_MANAGER_MODULE_HEADER Required Header
  33  *   \#include <sound_manager.h>
  34  *
  35  * @section CAPI_MEDIA_SOUND_MANAGER_OVERVIEW Overview
  36  * The Sound Manager service provides APIs to manage audio output.
  37  *
  38  * The Sound Manager API allows you to:
  39  * - check/control output volume
  40  * - change audio route policy
  41  * - handle volume changed notification
  42  * - handle audio route policy change notificat
  43  *
  44  * Current volume level can be checked with sound_manager_get_volume().
  45  * To get maximum supported volume level, call sound_manager_get_max_volume().
  46  * The volume level can be adjusted with sound_manager_set_volume().
  47  *
  48  * The Sound Manager has predefined types of sounds, such as ringtone, call, alarm, etc.  The type of the currently playing sound may be
  49  * obtained by calling sound_manager_get_current_sound_type().
  50  *
  51  * @subsection CAPI_MEDIA_SOUND_MANAGER_DESCRIPTION_ROUTE_POLICY Route policy
  52  * The route policy is responsible for selection of sound sources and outputs that should be active. \n
  53  * Note: The bluetooth headset microphone is used only in the voice call mode.
  54  * <p>
  55  * <ul>
  56  *    <li> The default audio route policy is #SOUND_ROUTE_DEFAULT <p></li>
  57  *    <table>
  58  *        <tr>
  59  *           <td><b>Mode</b></td>
  60  *           <td><b>Bluetooth headset</b></td>
  61  *           <td><b>Wired headset</b></td>
  62  *           <td><b>Used device</b></td>
  63  *        </tr>
  64  *        <tr>
  65  *           <td>PLAYBACK</td>
  66  *           <td>connected</td>
  67  *           <td>plugged</td>
  68  *           <td>Bluetooth headset</td>
  69  *        </tr>
  70  *        <tr>
  71  *           <td>PLAYBACK</td>
  72  *           <td>connected</td>
  73  *           <td>unplugged</td>
  74  *           <td>Bluetooth headset</td>
  75  *        </tr>
  76  *        <tr>
  77  *           <td>PLAYBACK</td>
  78  *           <td>disconnected</td>
  79  *           <td>plugged</td>
  80  *           <td>Wired headset</td>
  81  *        </tr>
  82  *        <tr>
  83  *           <td>PLAYBACK</td>
  84  *           <td>disconnected</td>
  85  *           <td>unplugged</td>
  86  *           <td>Loudspeaker</td>
  87  *        </tr>
  88  *        <tr>
  89  *           <td>CAPTURE</td>
  90  *           <td>connected</td>
  91  *           <td>plugged</td>
  92  *           <td>Wired headset microphone</td>
  93  *        </tr>
  94  *        <tr>
  95  *           <td>CAPTURE</td>
  96  *           <td>connected</td>
  97  *           <td>unplugged</td>
  98  *           <td>Microphone</td>
  99  *        </tr>
 100  *        <tr>
 101  *           <td>CAPTURE</td>
 102  *           <td>disconnected</td>
 103  *           <td>plugged</td>
 104  *           <td>Wired headset microphone</td>
 105  *        </tr>
 106  *        <tr>
 107  *           <td>CAPTURE</td>
 108  *           <td>disconnected</td>
 109  *           <td>unplugged</td>
 110  *           <td>Built-in microphone</td>
 111  *        </tr>
 112  *    </table>
 113  *
 114  *    <li> The bluetooth headset will be ignored for the routing policy set to #SOUND_ROUTE_IGNORE_A2DP <p></li>
 115  *    <table>
 116  *        <tr>
 117  *           <td><b>Mode</b></td>
 118  *           <td><b>Bluetooth headset</b></td>
 119  *           <td><b>Wired headset</b></td>
 120  *           <td><b>Used device</b></td>
 121  *        </tr>
 122  *        <tr>
 123  *           <td>PLAYBACK</td>
 124  *           <td>connected</td>
 125  *           <td>plugged</td>
 126  *           <td>Wired headset</td>
 127  *        </tr>
 128  *        <tr>
 129  *           <td>PLAYBACK</td>
 130  *           <td>connected</td>
 131  *           <td>unplugged</td>
 132  *           <td>Loudspeaker</td>
 133  *        </tr>
 134  *        <tr>
 135  *           <td>PLAYBACK</td>
 136  *           <td>disconnected</td>
 137  *           <td>plugged</td>
 138  *           <td>Wired headset</td>
 139  *        </tr>
 140  *        <tr>
 141  *           <td>PLAYBACK</td>
 142  *           <td>disconnected</td>
 143  *           <td>unplugged</td>
 144  *           <td>Loudspeaker</td>
 145  *        </tr>
 146  *        <tr>
 147  *           <td>CAPTURE</td>
 148  *           <td>connected</td>
 149  *           <td>plugged</td>
 150  *           <td>Wired headset microphone</td>
 151  *        </tr>
 152  *        <tr>
 153  *           <td>CAPTURE</td>
 154  *           <td>connected</td>
 155  *           <td>unplugged</td>
 156  *           <td>Microphone</td>
 157  *        </tr>
 158  *        <tr>
 159  *           <td>CAPTURE</td>
 160  *           <td>disconnected</td>
 161  *           <td>plugged</td>
 162  *           <td>Wired headset microphone</td>
 163  *        </tr>
 164  *        <tr>
 165  *           <td>CAPTURE</td>
 166  *           <td>disconnected</td>
 167  *           <td>unplugged</td>
 168  *           <td>Built-in microphone</td>
 169  *        </tr>
 170  *    </table>
 171  *
 172  *    <li> Only the loudspeaker and microphone will be used for the routing policy set to #SOUND_ROUTE_HANDSET_ONLY <p></li>
 173  *    <table>
 174  *        <tr>
 175  *           <td><b>Mode</b></td>
 176  *           <td><b>Bluetooth headset</b></td>
 177  *           <td><b>Wired headset</b></td>
 178  *           <td><b>Used device</b></td>
 179  *        </tr>
 180  *        <tr>
 181  *           <td>PLAYBACK</td>
 182  *           <td>connected</td>
 183  *           <td>plugged</td>
 184  *           <td>Loudspeaker</td>
 185  *        </tr>
 186  *        <tr>
 187  *           <td>PLAYBACK</td>
 188  *           <td>connected</td>
 189  *           <td>unplugged</td>
 190  *           <td>Loudspeaker</td>
 191  *        </tr>
 192  *        <tr>
 193  *           <td>PLAYBACK</td>
 194  *           <td>disconnected</td>
 195  *           <td>plugged</td>
 196  *           <td>Loudspeaker</td>
 197  *        </tr>
 198  *        <tr>
 199  *           <td>PLAYBACK</td>
 200  *           <td>disconnected</td>
 201  *           <td>unplugged</td>
 202  *           <td>Loudspeaker</td>
 203  *        </tr>
 204  *        <tr>
 205  *           <td>CAPTURE</td>
 206  *           <td>connected</td>
 207  *           <td>plugged</td>
 208  *           <td>Microphone</td>
 209  *        </tr>
 210  *        <tr>
 211  *           <td>CAPTURE</td>
 212  *           <td>connected</td>
 213  *           <td>unplugged</td>
 214  *           <td>Microphone</td>
 215  *        </tr>
 216  *        <tr>
 217  *           <td>CAPTURE</td>
 218  *           <td>disconnected</td>
 219  *           <td>plugged</td>
 220  *           <td>Microphone</td>
 221  *        </tr>
 222  *        <tr>
 223  *           <td>CAPTURE</td>
 224  *           <td>disconnected</td>
 225  *           <td>unplugged</td>
 226  *           <td>Microphone</td>
 227  *        </tr>
 228  *    </table>
 229  * </ul>
 230  *
 231  * The sound_manager_set_route_policy() and  sound_manager_get_route_policy() functions set and check the route policy, which is limited to the pre-defined policies described.
 232  *
 233  * @subsection CAPI_MEDIA_SOUND_MANAGER_LIFE_CYCLE_ASYNCHRONOUS_OPERATIONS Asynchronous operations
 234  * The Sound Manager API provides only asynchronous operations. \n
 235  * Thus the result will be passed to the application via the callback mechanism.
 236  * An appropriate callback can be called in response to changes initiated from outside the application. \n
 237  * Possible callbacks are listed below:
 238  * <p>
 239  * <ul>
 240  *    <li> sound_manager_volume_changed_cb - invoked when volume level is changed.<p></li>
 241  *    <li> sound_manager_route_policy_changed_cb - invoked when route policy is changed.<p></li>
 242  * </ul>
 243  *
 244  * @subsection CAPI_MEDIA_SOUND_MANAGER_MODULE_LIFE_CYCLE_CALLBACK_OPERATIONS  Callback(Event) Operations
 245  * The callback mechanism is used to notify the application about significant sound manager events.
 246  * <div><table class="doxtable" >
 247  *     <tr>
 248  *        <th><b> REGISTER</b></th>
 249  *        <th><b> UNREGISTER</b></th>
 250  *        <th><b> CALLBACK</b></th>
 251  *        <th><b> DESCRIPTION</b></th>
 252  *     </tr>
 253  *     <tr>
 254  *        <td> sound_manager_set_volume_changed_cb()</td>
 255  *        <td> sound_manager_unset_volume_changed_cb()</td>
 256  *        <td> sound_manager_volume_changed_cb()</td>
 257  *        <td> This callback is called when volume value is changed.</td>
 258  *     </tr>
 259  *     <tr>
 260  *        <td> sound_manager_set_route_policy_changed_cb()</td>
 261  *        <td> sound_manager_unset_route_policy_changed_cb()</td>
 262  *        <td> sound_manager_route_policy_changed_cb()</td>
 263  *        <td> This callback is called when the route policy is changed.</td>
 264  *     </tr>
 265  * </table></div>
 266  *
 267 */
 268
 269 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__ */