include/radio.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 #ifndef __TIZEN_MEDIA_RADIO_H__
  18 #define __TIZEN_MEDIA_RADIO_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 #define RADIO_ERROR_CLASS          TIZEN_ERROR_MULTIMEDIA_CLASS | 0x70
  27
  28 /**
  29  * @file radio.h
  30  * @brief This file contains the radio API.
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_MEDIA_RADIO_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief Radio handle type.
  40  */
  41 typedef struct radio_s *radio_h;
  42
  43 /**
  44  * @brief Enumerations of radio state
  45  */
  46 typedef enum
  47 {
  48         RADIO_STATE_READY,                      /**< Ready to play or scan */
  49         RADIO_STATE_PLAYING,            /**< Playing audio from the tuner */
  50         RADIO_STATE_SCANNING,           /**< Scanning Searching for the next station signal starts from a given starting frequency */
  51 } radio_state_e;
  52
  53 /**
  54  * @brief Error codes for radio
  55  */
  56 typedef enum
  57 {
  58                 RADIO_ERROR_NONE                        = TIZEN_ERROR_NONE,                                                                                      /**< Successful */
  59                 RADIO_ERROR_OUT_OF_MEMORY           = TIZEN_ERROR_OUT_OF_MEMORY,                            /**< Out of memory */
  60                 RADIO_ERROR_INVALID_PARAMETER  = TIZEN_ERROR_INVALID_PARAMETER,         /**< Invalid parameter */
  61                 RADIO_ERROR_INVALID_OPERATION   = TIZEN_ERROR_INVALID_OPERATION,                /**< Invalid operation */
  62                 RADIO_ERROR_INVALID_STATE           = RADIO_ERROR_CLASS | 0x01  ,                               /**< Invalid state */
  63                 RADIO_ERROR_SOUND_POLICY            = RADIO_ERROR_CLASS | 0x02  ,                               /**< Sound policy error */
  64 } radio_error_e;
  65
  66 /**
  67  * @brief Enumerations of radio interrupted type
  68  */
  69 typedef enum
  70 {
  71        RADIO_INTERRUPTED_BY_OTHER_APP = 0,                              /**< Interrupted by another application*/
  72        RADIO_INTERRUPTED_BY_CALL_START,                                         /**< Interrupted by call starting*/
  73        RADIO_INTERRUPTED_BY_CALL_END,                                                   /**< Interrupted by call ending*/
  74        RADIO_INTERRUPTED_BY_EARJACK_UNPLUG,                     /**< Interrupted by unplugging headphone*/
  75        RADIO_INTERRUPTED_BY_RESOURCE_CONFLICT,          /**< Interrupted by resource conflict*/
  76        RADIO_INTERRUPTED_BY_ALARM_START,                                        /**< Interrupted by alarm starting*/
  77        RADIO_INTERRUPTED_BY_ALARM_END,                                          /**< Interrupted by alarm ending*/
  78 } radio_interrupted_code_e;
  79
  80 /**
  81  * @brief  Called when the scan information is updated.
  82  * @param[in] frequency The tuned radio frequency [87500 ~ 108000] (kHz)
  83  * @param[in] user_data  The user data passed from the callback registration function
  84  * @pre It will be invoked by radio_scan_start()
  85  * @see radio_scan_start()
  86  */
  87 typedef void (*radio_scan_updated_cb)(int frequency, void *user_data);
  88
  89 /**
  90  * @brief  Called when the radio scan is stopped.
  91  * @param[in] user_data  The user data passed from the callback registration function
  92  * @pre It will be invoked when scan is stopped by radio_scan_stop()
  93  * @see radio_scan_stop()
  94  */
  95 typedef void (*radio_scan_stopped_cb)(void *user_data);
  96
  97 /**
  98  * @brief  Called when the radio scan is completed.
  99  * @param[in] user_data  The user data passed from the callback registration function
 100  * @pre It will be invoked when scan is completed if you register this callback using radio_set_scan_completed_cb()
 101  * @see radio_scan_start()
 102  * @see radio_set_scan_completed_cb()
 103  * @see radio_unset_scan_completed_cb()
 104  */
 105 typedef void (*radio_scan_completed_cb)(void *user_data);
 106
 107 /**
 108  * @brief  Called when the radio seek is completed.
 109  * @param[in] frequency The current frequency [87500 ~ 108000] (kHz)
 110  * @param[in] user_data  The user data passed from the callback registration function
 111  * @pre It will be invoked when radio seek completed if you register this callback using radio_seek_up() or radio_seek_down()
 112  * @see radio_seek_up()
 113  * @see radio_seek_down()
 114  */
 115 typedef void (*radio_seek_completed_cb)(int frequency, void *user_data);
 116
 117 /**
 118  * @brief  Called when the radio is interrupted.
 119  * @param[in]   error_code      The interrupted error code
 120  * @param[in]   user_data       The user data passed from the callback registration function
 121  * @see radio_set_interrupted_cb()
 122  * @see radio_unset_interrupted_cb()
 123  */
 124 typedef void (*radio_interrupted_cb)(radio_interrupted_code_e code, void *user_data);
 125
 126 /**
 127  * @brief Creates a radio handle.
 128  * @remarks @a radio must be released radio_destroy() by you.
 129  * @param[out]  radio  A new handle to radio
 130  * @retval #RADIO_ERROR_NONE Successful
 131  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 132  * @retval #RADIO_ERROR_OUT_OF_MEMORY Out of memory
 133  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 134  * @see radio_destroy()
 135  */
 136 int radio_create(radio_h *radio);
 137
 138 /**
 139  * @brief Destroys the radio handle and releases all its resources.
 140  *
 141  * @remarks To completely shutdown radio operation, call this function with a valid radio handle.
 142  *
 143  * @param[in]           radio The handle to radio to be destroyed
 144  * @return 0 on success, otherwise a negative error value.
 145  * @retval #RADIO_ERROR_NONE Successful
 146  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 147  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 148  * @see radio_create()
 149  */
 150 int radio_destroy(radio_h radio);
 151
 152 /**
 153  * @brief Gets the radio's current state.
 154  * @param[in]   radio   The handle to radio
 155  * @param[out]  state   The current state of the radio
 156  * @return 0 on success, otherwise a negative error value.
 157  * @retval #RADIO_ERROR_NONE Successful
 158  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 159  */
 160 int  radio_get_state(radio_h radio, radio_state_e *state);
 161
 162 /**
 163  * @brief Starts playing radio.
 164  *
 165  * @param[in]   radio The handle to radio
 166  * @return 0 on success, otherwise a negative error value.
 167  * @retval #RADIO_ERROR_NONE Successful
 168  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 169  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 170  * @retval #RADIO_ERROR_SOUND_POLICY Sound policy error
 171  * @pre The radio state must be #RADIO_STATE_READY by radio_create().
 172  * @post The radio state will be #RADIO_STATE_PLAYING.
 173  * @see radio_stop()
 174  */
 175 int radio_start(radio_h radio);
 176
 177 /**
 178  * @brief Stops playing radio.
 179  * @param[in]   radio The handle to radio
 180  * @return 0 on success, otherwise a negative error value.
 181  * @retval #RADIO_ERROR_NONE Successful
 182  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
 183  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 184  * @pre The radio state must be either #RADIO_STATE_PLAYING by radio_start().
 185  * @post The radio state will be #RADIO_STATE_READY.
 186  * @see radio_start()
 187  * @see radio_scan_start()
 188  */
 189 int radio_stop(radio_h radio);
 190
 191 /**
 192  * @brief Seeks up the effective frequency of radio, asynchronously.
 193  * @param[in]   radio The handle to radio
 194  * @param[in] callback  The callback function to register
 195  * @param[in] user_data The user data to be passed to the callback function
 196  * @return 0 on success, otherwise a negative error value.
 197  * @retval #RADIO_ERROR_NONE Successful
 198  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 199  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 200  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 201  * @pre The radio state must be #RADIO_STATE_PLAYING by radio_start().
 202  * @post It invokes radio_seek_completed_cb() when seek completes.
 203  * @see radio_seek_down()
 204  */
 205 int radio_seek_up(radio_h radio,radio_seek_completed_cb callback, void *user_data );
 206
 207 /**
 208  * @brief Seeks down the effective frequency of radio, asynchronously.
 209  * @param[in]   radio The handle to radio
 210  * @param[in] callback  The callback function to register
 211  * @param[in] user_data The user data to be passed to the callback function
 212  * @return 0 on success, otherwise a negative error value.
 213  * @retval #RADIO_ERROR_NONE Successful
 214  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 215  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 216  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 217  * @pre The radio state must be #RADIO_STATE_PLAYING by radio_start().
 218  * @post It invokes radio_seek_completed_cb() when seek completes.
 219  * @see radio_seek_up()
 220  */
 221 int radio_seek_down(radio_h radio,radio_seek_completed_cb callback, void *user_data );
 222
 223 /**
 224  * @brief Sets the radio frequency.
 225  * @param[in]   radio The handle to radio
 226  * @param[in]   percent The frequency to set [87500 ~ 108000] (kHz)
 227  * @return 0 on success, otherwise a negative error value.
 228  * @retval #RADIO_ERROR_NONE Successful
 229  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 230  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 231  * @see radio_get_frequency()
 232  */
 233 int radio_set_frequency(radio_h radio, int frequency);
 234
 235 /**
 236  * @brief Gets the current frequency of radio.
 237  * @param[in]   radio The handle to radio
 238  * @param[out]  frequency The current frequency [87500 ~ 108000] (kHz)
 239  * @return 0 on success, otherwise a negative error value.
 240  * @retval #RADIO_ERROR_NONE Successful
 241  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 242  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 243  * @see radio_set_frequency()
 244  */
 245 int radio_get_frequency(radio_h radio, int *frequency);
 246
 247 /**
 248  * @brief Starts scanning radio signals, asynchronously
 249  *
 250  * @param[in]   radio The handle to radio
 251  * @param[in] callback  The callback function to register
 252  * @param[in] user_data The user data to be passed to the callback function
 253  * @return 0 on success, otherwise a negative error value.
 254  * @retval #RADIO_ERROR_NONE Successful
 255  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 256  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 257  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 258  * @pre The radio state must be #RADIO_STATE_READY by either radio_create() or radio_stop().
 259  * @post The radio state will be #RADIO_STATE_SCANNING during searching. After scan is completed, radio state will be #RADIO_STATE_READY.
 260  * @post It invokes radio_scan_updated_cb() when the scan information updates.
 261  * @post It invokes radio_scan_completed_cb() when scan completes, if you set a callback with radio_set_scan_completed_cb().
 262  * @see radio_scan_stop()
 263  * @see radio_set_scan_completed_cb()
 264  * @see radio_scan_completed_cb()
 265  */
 266 int radio_scan_start(radio_h radio, radio_scan_updated_cb callback, void *user_data);
 267
 268 /**
 269  * @brief Stops scanning radio signals, asynchronously.
 270  * @param[in]   radio The handle to radio
 271  * @param[in] callback  The callback function to register
 272  * @param[in] user_data The user data to be passed to the callback function
 273  * @return 0 on success, otherwise a negative error value.
 274  * @retval #RADIO_ERROR_NONE Successful
 275  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
 276  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 277  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 278  * @pre The radio state must be #RADIO_STATE_SCANNING by radio_scan_start().
 279  * @post It invokes radio_scan_stopped_cb() when the scan stops.
 280  * @post The radio state will be #RADIO_STATE_READY.
 281  * @see radio_scan_start()
 282  */
 283 int radio_scan_stop(radio_h radio, radio_scan_stopped_cb callback, void *user_data);
 284
 285 /**
 286  * @brief Sets the radio's mute status.
 287  * @details  If the mute status is @c true, no sounds will be played. If @c false, sounds will be played. Until this function is called, by default the radio is not muted.
 288  * @param[in]   radio The handle to radio
 289  * @param[in]   muted New mute status: (@c true = mute, @c false = not muted)
 290  * @return 0 on success, otherwise a negative error value.
 291  * @retval #RADIO_ERROR_NONE Successful
 292  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 293  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 294  * @see radio_is_muted()
 295  */
 296 int radio_set_mute(radio_h radio, bool muted);
 297
 298 /**
 299  * @brief Gets the radio's mute status.
 300  * @details If the mute status is @c true, no sounds are played. If @c false, sounds are played.
 301  * @param[in]   radio The handle to radio
 302  * @param[out]  muted  The current mute status: (@c true = mute, @c false = not muted)
 303  * @return 0 on success, otherwise a negative error value.
 304  * @retval #RADIO_ERROR_NONE Successful
 305  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 306  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 307  * @see radio_set_mute()
 308  */
 309 int radio_is_muted(radio_h radio, bool *muted);
 310
 311 /**
 312  * @brief Registers a callback function to be invoked when the scan finishes.
 313  * @param[in] radio     The handle to radio
 314  * @param[in] callback  The callback function to register
 315  * @param[in] user_data The user data to be passed to the callback function
 316  * @return 0 on success, otherwise a negative error value.
 317  * @retval #RADIO_ERROR_NONE Successful
 318  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 320  * @post  radio_scan_completed_cb() will be invoked
 321  * @see radio_unset_scan_completed_cb()
 322  * @see radio_scan_completed_cb()
 323  */
 324 int radio_set_scan_completed_cb(radio_h radio, radio_scan_completed_cb callback, void *user_data);
 325
 326 /**
 327  * @brief       Unregisters the callback function.
 328  * @param[in] radio The handle to radio
 329  * @return 0 on success, otherwise a negative error value.
 330  * @retval #RADIO_ERROR_NONE Successful
 331  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 332  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 333  * @see radio_set_scan_completed_cb()
 334  */
 335 int radio_unset_scan_completed_cb(radio_h radio);
 336
 337 /**
 338  * @brief Registers a callback function to be invoked when the radio is interrupted.
 339  * @param[in] radio     The handle to radio
 340  * @param[in] callback  The callback function to register
 341  * @param[in] user_data The user data to be passed to the callback function
 342  * @return 0 on success, otherwise a negative error value.
 343  * @retval #RADIO_ERROR_NONE Successful
 344  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 345  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 346  * @post  radio_interrupted_cb() will be invoked
 347  * @see radio_unset_interrupted_cb()
 348  * @see #radio_interrupted_code_e
 349  * @see radio_interrupted_cb()
 350  */
 351 int radio_set_interrupted_cb(radio_h radio, radio_interrupted_cb callback, void *user_data);
 352
 353 /**
 354  * @brief Unregisters the callback function.
 355  * @param[in] radio The handle to radio
 356  * @return 0 on success, otherwise a negative error value.
 357  * @retval #RADIO_ERROR_NONE Successful
 358  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 359  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 360  * @see radio_set_interrupted_cb()
 361  */
 362 int radio_unset_interrupted_cb(radio_h radio);
 363
 364 /**
 365  * @}
 366  */
 367
 368 #ifdef __cplusplus
 369 }
 370 #endif
 371
 372 #endif /* __TIZEN_MEDIA_RADIO_H__ */