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 and session policy.
  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 a sound session policy
  42  * - handle the notification of a sound session interruption
  43  * - query the basic information of connected sound devices
  44  * - handle the notification for connection of a sound device, and for changed information of a sound device
  45  *
  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:
  51  * <p>
  52  * <ul>
  53  *    <li> sound_manager_volume_changed_cb() - invoked when volume level is changed.<p></li>
  54  *    <li> sound_session_interrupted_cb() - invoked when the session is interrupted.<p></li>
  55  *    <li> sound_device_connected_cb() - invoked when the connection of a sound device is changed.<p></li>
  56  *    <li> sound_device_information_changed_cb() - invoked when the information of a sound device is changed.<p></li>
  57  * </ul>
  58  *
  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" >
  62  *     <tr>
  63  *        <th><b> REGISTER</b></th>
  64  *        <th><b> UNREGISTER</b></th>
  65  *        <th><b> CALLBACK</b></th>
  66  *        <th><b> DESCRIPTION</b></th>
  67  *     </tr>
  68  *     <tr>
  69  *        <td> sound_manager_set_volume_changed_cb()</td>
  70  *        <td> sound_manager_unset_volume_changed_cb()</td>
  71  *        <td> sound_manager_volume_changed_cb()</td>
  72  *        <td> This callback is called when volume value is changed.</td>
  73  *     </tr>
  74  *     <tr>
  75  *        <td> sound_manager_set_session_interrupted_cb()</td>
  76  *        <td> sound_manager_unset_session_interrupted_cb()</td>
  77  *        <td> sound_session_interrupted_cb()</td>
  78  *        <td> This callback is called when audio session is interrupted.</td>
  79  *     </tr>
  80  *     <tr>
  81  *        <td> sound_manager_set_device_connected_cb()</td>
  82  *        <td> sound_manager_unset_device_connected_cb()</td>
  83  *        <td> sound_device_connected_cb()</td>
  84  *        <td> This callback is called when the connection of a sound device is changed.</td>
  85  *     </tr>
  86  *     <tr>
  87  *        <td> sound_manager_set_device_information_changed_cb()</td>
  88  *        <td> sound_manager_unset_device_information_changed_cb()</td>
  89  *        <td> sound_device_information_changed_cb()</td>
  90  *        <td> This callback is called when the information of a sound device is changed.</td>
  91  *     </tr>
  92  * </table></div>
  93  *
  94 */
  95
  96 /**
  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>
 102  *
 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
 107  *
 108  * The Sound Manager has predefined types of sounds.(system, notification, alarm, ringtone, media, call, voip, voice).
 109  *
 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().
 113  *
 114  * The type of currently playing sound may be obtained by calling sound_manager_get_current_sound_type().
 115  * To set the type of the currently playing sound forcibly, call sound_manager_set_current_sound_type().
 116  *
 117  *
 118 */
 119
 120 /**
 121  * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
 122  * @defgroup CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE Session
 123  * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE API provides functions to control a session.
 124  * @section CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE_HEADER Required Header
 125  *    \#include <sound_manager.h>
 126  *
 127  * @section CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE_OVERVIEW Overview
 128  * The Sound Manager Session API allows you to:
 129  * - determine a sound session policy
 130  * - handle the notification of a sound session interruption
 131  *
 132  * The Sound Manager has predefined sound sessions (media, alarm, notification, emergency, voip)
 133  *
 134  * @section CAPI_MEDIA_SOUND_MANAGER_MODULE_FEATURE Related Features
 135  * APIs for voip sound session are related with the following features:\n
 136  *  - http://tizen.org/feature/microphone\n
 137  *  - http://tizen.org/feature/sip.voip\n
 138  *
 139  * It is recommended to design feature related codes in your application for reliability.\n
 140  *
 141  * 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
 142  *
 143  * 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
 144  *
 145  * 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>
 146  *
 147 */
 148
 149 /**
 150  * @ingroup CAPI_MEDIA_SOUND_MANAGER_MODULE
 151  * @defgroup CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE Device
 152  * @brief The @ref CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE API provides functions to query the information of sound devices.
 153  * @section CAPI_MEDIA_SOUND_MANAGER_DEIVCE_MODULE_HEADER Required Header
 154  *    \#include <sound_manager.h>
 155  *
 156  * @section CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE_OVERVIEW Overview
 157  * The Sound Manager Device API allows you to:
 158  * - query the basic information of connected sound devices.
 159  * - handle the sound device's connection and information change notification.
 160  *
 161  * The list of currently connected sound device can be obtained by calling sound_manager_get_current_device_list().
 162  * To get the handle of each sound device, call sound_manager_get_next_device() and sound_manager_get_prev_device().
 163  *
 164  * Device information, such as "type", "IO direction", "state", "ID", "name", can be obtained by calling corresponding APIs.
 165  *
 166  *
 167 */
 168
 169 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__ */