doc/radio_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_RADIO_DOC_H__
  19 #define __TIZEN_MEDIA_RADIO_DOC_H__
  20
  21
  22 /**
  23  * @file radio_doc.h
  24  * @brief This file contains high level documentation of the Multimedia Service.
  25  */
  26
  27 /**
  28  * @ingroup CAPI_MEDIA_FRAMEWORK
  29  * @defgroup CAPI_MEDIA_RADIO_MODULE Radio
  30  * @brief  The @ref CAPI_MEDIA_RADIO_MODULE APIs provide functions for accessing the radio.
  31  *
  32  * @section CAPI_MEDIA_RADIO_MODULE_HEADER Required Header
  33  *   \#include <radio.h>
  34  *
  35  * @section CAPI_MEDIA_RADIO_MODULE_OVERVIEW Overview
  36  *
  37  * The Radio API provides support for using the Radio.
  38  * The API allows :
  39  * - Starting and stopping the radio
  40  * - Seeking radio frequency
  41  * - Scanning radio signals
  42  * - Getting the state of the radio
  43  *
  44  * A radio handle (#radio_h) is created by calling the radio_create() function and can be started by using the radio_start() function.
  45  * It provides functions to start (radio_scan_start()) and stop (radio_scan_stop()) radio signal scanning. The radio frequency
  46  * seek up and seek down can be done asynchronously by calling the radio_seek_up() and radio_seek_down() functions respectively.
  47  * It also provides functions to get (radio_get_frequency()) and set (radio_set_frequency()) frequency for the given radio handle.
  48  *
  49  * @subsection CAPI_MEDIA_RADIO_LIFE_CYCLE_STATE_DIAGRAM State Diagram
  50  * The radio API is controlled by a state machine.
  51  * The following diagram shows the life cycle and the states of the Radio.
  52  * @image html capi_media_radio_state_diagram.png
  53  *
  54  *
  55  * @subsection CAPI_MEDIA_RADIO_LIFE_CYCLE_STATE_TRANSITIONS State Transitions
  56  * <div><table class="doxtable" >
  57  *     <tr>
  58  *        <th><b>FUNCTION</b></th>
  59  *        <th><b>PRE-STATE</b></th>
  60  *        <th><b>POST-STATE</b></th>
  61  *        <th><b>SYNC TYPE</b></th>
  62  *     </tr>
  63  *     <tr>
  64  *        <td>radio_create()</td>
  65  *        <td>NONE</td>
  66  *        <td>READY</td>
  67  *        <td>SYNC</td>
  68  *     </tr>
  69  *     <tr>
  70  *         <td>radio_destroy()</td>
  71  *         <td>READY</td>
  72  *         <td>NONE</td>
  73  *         <td>SYNC</td>
  74  *     </tr>
  75  *     <tr>
  76  *        <td>radio_start()</td>
  77  *        <td>READY</td>
  78  *        <td>PLAYING</td>
  79  *        <td>ASYNC</td>
  80  *     </tr>
  81  *     <tr>
  82  *        <td>radio_stop()</td>
  83  *        <td>PLAYING</td>
  84  *        <td>READY</td>
  85  *        <td>ASYNC</td>
  86  *     </tr>
  87  *     <tr>
  88  *        <td>radio_scan_start()</td>
  89  *        <td>READY</td>
  90  *        <td>SCANNING</td>
  91  *        <td>ASYNC</td>
  92  *     </tr>
  93  *     <tr>
  94  *        <td>radio_scan_stop()</td>
  95  *        <td>SCANNING</td>
  96  *        <td>READY</td>
  97  *        <td>ASYNC</td>
  98  *     </tr>
  99  *     <tr>
 100  *        <td>radio_seek_up()</td>
 101  *        <td>PLAYING</td>
 102  *        <td>PLAYING</td>
 103  *        <td>SYNC</td>
 104  *     </tr>
 105  *     <tr>
 106  *        <td>radio_seek_down()</td>
 107  *        <td>PLAYING</td>
 108  *        <td>PLAYING</td>
 109  *        <td>SYNC</td>
 110  *     </tr>
 111  * </table></div>
 112  *
 113  *
 114  * This API also gives notifications for radio's state change events by a callback mechanism.
 115  * @subsection CAPI_MEDIA_RADIO_LIFE_CYCLE_CALLBACK_OPERATIONS Callback(Event) Operations
 116  * The callback mechanism is used to notify the application about radio events.
 117  * <div><table class="doxtable" >
 118  *     <tr>
 119  *        <th><b>REGISTER</b></th>
 120  *        <th><b>UNREGISTER</b></th>
 121  *        <th><b>CALLBACK</b></th>
 122  *        <th><b>DESCRIPTION</b></th>
 123  *     </tr>
 124  *     <tr>
 125  *        <td>radio_set_scan_completed_cb()</td>
 126  *        <td>radio_unset_scan_completed_cb()</td>
 127  *        <td> radio_scan_completed_cb()</td>
 128  *        <td>This callback is invoked when the scan is completed </td>
 129  *     </tr>
 130  *               <tr>
 131  *        <td>radio_set_interrupted_cb()</td>
 132  *        <td>radio_unset_interrupted_cb()</td>
 133  *        <td>radio_interrupted_cb()</td>
 134  *        <td>This callback is used to notify when the radio is interrupted </td>
 135  *     </tr>
 136  *</table></div>
 137   * @section CAPI_MEDIA_RADIO_MODULE_FEATURE Related Features
 138  * This API is related with the following features:\n
 139  *  - http://tizen.org/feature/fmradio\n
 140  *
 141  * It is recommended to design feature related codes in your application for reliability.\n
 142  *
 143  * 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
 144  *
 145  * 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
 146  *
 147  * 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>
 148  *
 149  *
 150  */
 151
 152 #endif /* __TIZEN_MEDIA_RADIO_DOC_H__ */