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  * @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, session policy and devices.
  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 allows APIs to manage audio output.
  37  *
  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  * - determine a sound session policy (Deprecated)
  44  * - handle the notification of a sound session interruption (Deprecated)
  45  * - query the basic information of connected sound devices
  46  * - handle the notification for connection of a sound device, and for changed information of a sound device
  47  *
  48  * @subsection CAPI_MEDIA_SOUND_MANAGER_LIFE_CYCLE_ASYNCHRONOUS_OPERATIONS Asynchronous operations
  49  * The Sound Manager API allows only asynchronous operations. \n
  50  * Thus the result will be passed to the application via the callback mechanism.
  51  * An appropriate callback can be called in response to changes initiated from outside the application. \n
  52  * Possible callbacks are listed below:
  53  * <p>
  54  * <ul>
  55  *    <li> sound_manager_volume_changed_cb() - invoked when volume level is changed.<p></li>
  56  *    <li> sound_stream_focus_state_changed_cb() - invoked when the state of focus that belongs to the stream_info is changed.<p></li>
  57  *    <li> sound_stream_focus_state_watch_cb() - invoked when the focus state for each sound stream type is changed.<p></li>
  58  *    <li> sound_session_interrupted_cb() - invoked when the session is interrupted. (Deprecated)<p></li>
  59  *    <li> sound_device_connected_cb() - invoked when the connection of a sound device is changed.<p></li>
  60  *    <li> sound_device_information_changed_cb() - invoked when the information of a sound device is changed.<p></li>
  61  * </ul>
  62  *
  63  * @subsection CAPI_MEDIA_SOUND_MANAGER_MODULE_LIFE_CYCLE_CALLBACK_OPERATIONS  Callback(Event) Operations
  64  * The callback mechanism is used to notify the application about significant sound manager events.
  65  * <div><table class="doxtable" >
  66  *     <tr>
  67  *        <th><b> REGISTER</b></th>
  68  *        <th><b> UNREGISTER</b></th>
  69  *        <th><b> CALLBACK</b></th>
  70  *        <th><b> DESCRIPTION</b></th>
  71  *     </tr>
  72  *     <tr>
  73  *        <td> sound_manager_set_volume_changed_cb()</td>
  74  *        <td> sound_manager_unset_volume_changed_cb()</td>
  75  *        <td> sound_manager_volume_changed_cb()</td>
  76  *        <td> This callback is called when volume value is changed.</td>
  77  *     </tr>
  78  *     <tr>
  79  *        <td> sound_manager_create_stream_information()</td>
  80  *        <td> sound_manager_destroy_stream_information()</td>
  81  *        <td> sound_stream_focus_state_changed_cb()</td>
  82  *        <td> This callback is called when the state of focus that belongs to the stream_info is changed.</td>
  83  *     </tr>
  84  *     <tr>
  85  *        <td> sound_manager_add_focus_state_watch_cb()</td>
  86  *        <td> sound_manager_remove_foucs_state_watch_cb()</td>
  87  *        <td> sound_stream_focus_state_watch_cb()</td>
  88  *        <td> This callback is called when the focus state for each sound stream type is changed regardless of the process.</td>
  89  *     </tr>
  90  *     <tr>
  91  *        <td> sound_manager_set_session_interrupted_cb()</td>
  92  *        <td> sound_manager_unset_session_interrupted_cb()</td>
  93  *        <td> sound_session_interrupted_cb()</td>
  94  *        <td> This callback is called when audio session is interrupted. (Deprecated)</td>
  95  *     </tr>
  96  *     <tr>
  97  *        <td> sound_manager_set_device_connected_cb()</td>
  98  *        <td> sound_manager_unset_device_connected_cb()</td>
  99  *        <td> sound_device_connected_cb()</td>
 100  *        <td> This callback is called when the connection of a sound device is changed.</td>
 101  *     </tr>
 102  *     <tr>
 103  *        <td> sound_manager_set_device_information_changed_cb()</td>
 104  *        <td> sound_manager_unset_device_information_changed_cb()</td>
 105  *        <td> sound_device_information_changed_cb()</td>
 106  *        <td> This callback is called when the information of a sound device is changed.</td>
 107  *     </tr>
 108  * </table></div>
 109  *
 110 */
 111
 112 /**
 113  * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
 114  * @defgroup CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE Volume
 115  * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE API provides functions to check and control volumes.
 116  * @section CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE_HEADER Required Header
 117  *    \#include <sound_manager.h>
 118  *
 119  * @section CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE_OVERVIEW Overview
 120  * The Sound Manager Volume API allows you to:
 121  * - check/control output volumes
 122  * - handle a volume changed notification
 123  *
 124  * The Sound Manager has predefined types of sounds.(system, notification, alarm, ringtone, media, call, voip, voice).
 125  *
 126  * Current volume level of each type can be checked with sound_manager_get_volume().
 127  * To get the maximum supported volume level of each type, call sound_manager_get_max_volume().
 128  * The volume level of each type can be adjusted with sound_manager_set_volume().
 129  *
 130  * The type of currently playing sound may be obtained by calling sound_manager_get_current_sound_type().
 131  * To set the type of the currently playing sound forcibly, call sound_manager_set_current_sound_type().
 132  *
 133  *
 134 */
 135
 136 /**
 137  * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
 138  * @defgroup CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE Stream Policy
 139  * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE API provides functions to control a sound stream.
 140  * @section CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE_HEADER Required Header
 141  *    \#include <sound_manager.h>
 142  *
 143  * @section CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE_OVERVIEW Overview
 144  * The Sound Manager Stream API allows you to:
 145  * - determine/control a sound stream policy
 146  * - handle the notification of a sound focus status change
 147  *
 148  * The Sound Manager has predefined sound stream types (media, system, alarm, notification, emergency, voip, etc)
 149  *
 150 */
 151
 152 /**
 153  * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
 154  * @defgroup CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE Session
 155  * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE API provides functions to control a session. (Deprecated)
 156  * @section CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE_HEADER Required Header
 157  *    \#include <sound_manager.h>
 158  *
 159  * @section CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE_OVERVIEW Overview
 160  * The Sound Manager Session API allows you to:
 161  * - determine a sound session policy
 162  * - handle the notification of a sound session interruption
 163  *
 164  * The Sound Manager has predefined sound sessions (media, alarm, notification, emergency, voip)
 165  *
 166  * @section CAPI_MEDIA_SOUND_MANAGER_MODULE_FEATURE Related Features
 167  * APIs for voip sound session and voip stream type are related with the following features:\n
 168  *  - http://tizen.org/feature/microphone\n
 169  *
 170  * It is recommended to design feature related codes in your application for reliability.\n
 171  *
 172  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
 173  *
 174  * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
 175  *
 176  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 177  *
 178 */
 179
 180 /**
 181  * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
 182  * @defgroup CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE Device
 183  * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE API provides functions to query the information of sound devices.
 184  * @section CAPI_MEDIA_SOUND_MANAGER_DEIVCE_MODULE_HEADER Required Header
 185  *    \#include <sound_manager.h>
 186  *
 187  * @section CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE_OVERVIEW Overview
 188  * The Sound Manager Device API allows you to:
 189  * - query the basic information of connected sound devices.
 190  * - handle the sound device's connection and information change notification.
 191  *
 192  * The list of currently connected sound device can be obtained by calling sound_manager_get_current_device_list().
 193  * To get the handle of each sound device, call sound_manager_get_next_device() and sound_manager_get_prev_device().
 194  *
 195  * Device information, such as "type", "IO direction", "state", "ID", "name", can be obtained by calling corresponding APIs.
 196  *
 197  *
 198 */
 199
 200 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__ */