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 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  * - query the basic information of connected sound devices
  44  * - handle the notification for connection 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_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>
  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_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>
  73  *     </tr>
  74  *     <tr>
  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>
  79  *     </tr>
  80  *     <tr>
  81  *        <td> sound_manager_add_focus_state_watch_cb()</td>
  82  *        <td> sound_manager_remove_foucs_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>
  85  *     </tr>
  86  *     <tr>
  87  *        <td> sound_manager_add_device_connection_changed_cb()</td>
  88  *        <td> sound_manager_remove_device_connection_changed_cb()</td>
  89  *        <td> sound_device_connected_cb()</td>
  90  *        <td> This callback is called when the connection 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  *
 116  *
 117 */
 118
 119 /**
 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>
 125  *
 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
 130  *
 131  * The Sound Manager has predefined sound stream types (media, system, alarm, notification, emergency, voip, etc)
 132  *
 133 */
 134
 135 /**
 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>
 141  *
 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.
 146  *
 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().
 149  *
 150  * Device information, such as "type", "IO direction", "ID", "name", can be obtained by calling corresponding APIs.
 151  *
 152  *
 153 */
 154
 155 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_DOC_H__ */