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 /**
  27  * @file radio.h
  28  * @brief This file contains the radio API.
  29  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_MEDIA_RADIO_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Radio type handle.
  39  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  40  */
  41 typedef struct radio_s *radio_h;
  42
  43 /**
  44  * @brief Enumeration of radio state.
  45  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  46  */
  47 typedef enum
  48 {
  49         RADIO_STATE_READY,                      /**< Ready to play or scan */
  50         RADIO_STATE_PLAYING,            /**< Playing the audio from the tuner */
  51         RADIO_STATE_SCANNING,           /**< Scanning/Searching for the next station signal that starts from a given starting frequency */
  52 } radio_state_e;
  53
  54 /**
  55  * @brief Enumeration of error codes for the radio.
  56  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  57  */
  58 typedef enum
  59 {
  60         RADIO_ERROR_NONE                        = TIZEN_ERROR_NONE,                                                             /**< Successful */
  61         RADIO_ERROR_OUT_OF_MEMORY           = TIZEN_ERROR_OUT_OF_MEMORY,                                /**< Out of memory */
  62         RADIO_ERROR_INVALID_PARAMETER  = TIZEN_ERROR_INVALID_PARAMETER,                 /**< Invalid parameter */
  63         RADIO_ERROR_INVALID_OPERATION   = TIZEN_ERROR_INVALID_OPERATION,                        /**< Invalid operation */
  64         RADIO_ERROR_INVALID_STATE           = TIZEN_ERROR_RADIO | 0x01  ,                                       /**< Invalid state */
  65         RADIO_ERROR_SOUND_POLICY            = TIZEN_ERROR_RADIO | 0x02  ,                                       /**< Sound policy error */
  66         RADIO_ERROR_PERMISSION_DENIED   = TIZEN_ERROR_PERMISSION_DENIED,                        /**< Permission denied */
  67         RADIO_ERROR_NOT_SUPPORTED   = TIZEN_ERROR_NOT_SUPPORTED,                                        /**< Not supported */
  68 } radio_error_e;
  69
  70 /**
  71  * @brief Enumeration of radio interrupted type.
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73  */
  74 typedef enum
  75 {
  76        RADIO_INTERRUPTED_COMPLETED = 0,                                 /**< Interrupt completed */
  77        RADIO_INTERRUPTED_BY_MEDIA,                                              /**< Interrupted by a non-resumable media application */
  78        RADIO_INTERRUPTED_BY_CALL,                                               /**< Interrupted by an incoming call */
  79        RADIO_INTERRUPTED_BY_EARJACK_UNPLUG,                     /**< Interrupted by unplugging headphones */
  80        RADIO_INTERRUPTED_BY_RESOURCE_CONFLICT,          /**< Interrupted by a resource conflict */
  81        RADIO_INTERRUPTED_BY_ALARM,                                              /**< Interrupted by an alarm */
  82        RADIO_INTERRUPTED_BY_EMERGENCY,                          /**< Interrupted by an emergency */
  83        RADIO_INTERRUPTED_BY_RESUMABLE_MEDIA,                    /**< Interrupted by a resumable media application */
  84        RADIO_INTERRUPTED_BY_NOTIFICATION,                               /**< Interrupted by a notification */
  85 } radio_interrupted_code_e;
  86
  87 /**
  88  * @brief  Called when the scan information is updated.
  89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  90  * @param[in] frequency The tuned radio frequency [87500 ~ 108000] (kHz)
  91  * @param[in] user_data  The user data passed from the callback registration function
  92  * @pre It will be invoked by radio_scan_start().
  93  * @see radio_scan_start()
  94  */
  95 typedef void (*radio_scan_updated_cb)(int frequency, void *user_data);
  96
  97 /**
  98  * @brief  Called when the radio scan is stopped.
  99  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 100  * @param[in] user_data  The user data passed from the callback registration function
 101  * @pre It will be invoked when the scan is stopped by radio_scan_stop().
 102  * @see radio_scan_stop()
 103  */
 104 typedef void (*radio_scan_stopped_cb)(void *user_data);
 105
 106 /**
 107  * @brief  Called when the radio scan is completed.
 108  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 109  * @param[in] user_data  The user data passed from the callback registration function
 110  * @pre It will be invoked when the scan is completed by registering this callback using radio_set_scan_completed_cb().
 111  * @see radio_scan_start()
 112  * @see radio_set_scan_completed_cb()
 113  * @see radio_unset_scan_completed_cb()
 114  */
 115 typedef void (*radio_scan_completed_cb)(void *user_data);
 116
 117 /**
 118  * @brief  Called when the radio seek is completed.
 119  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 120  * @param[in] frequency The current frequency [87500 ~ 108000] (kHz)
 121  * @param[in] user_data  The user data passed from the callback registration function
 122  * @pre It will be invoked when the radio seek is completed by registering this callback using radio_seek_up() or radio_seek_down().
 123  * @see radio_seek_up()
 124  * @see radio_seek_down()
 125  */
 126 typedef void (*radio_seek_completed_cb)(int frequency, void *user_data);
 127
 128 /**
 129  * @brief  Called when the radio is interrupted.
 130  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 131  * @param[in]   error_code      The interrupted error code
 132  * @param[in]   user_data       The user data passed from the callback registration function
 133  * @see radio_set_interrupted_cb()
 134  * @see radio_unset_interrupted_cb()
 135  */
 136 typedef void (*radio_interrupted_cb)(radio_interrupted_code_e code, void *user_data);
 137
 138 /**
 139  * @brief Creates a radio handle.
 140  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 141  * @remarks You must release @a radio using radio_destroy().
 142  * @param[out]  radio  A new handle to radio
 143  * @retval #RADIO_ERROR_NONE Successful
 144  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 145  * @retval #RADIO_ERROR_OUT_OF_MEMORY Out of memory
 146  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 147  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 148  * @see radio_destroy()
 149  */
 150 int radio_create(radio_h *radio);
 151
 152 /**
 153  * @brief Destroys the radio handle and releases all its resources.
 154  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 155  * @remarks To completely shutdown the radio operation, call this function with a valid radio handle.
 156  *
 157  * @param[in]           radio The handle to radio to be destroyed
 158  * @return @c 0 on success,
 159  *         otherwise a negative error value
 160  * @retval #RADIO_ERROR_NONE Successful
 161  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 162  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 163  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 164  * @see radio_create()
 165  */
 166 int radio_destroy(radio_h radio);
 167
 168 /**
 169  * @brief Gets the radio's current state.
 170  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 171  * @param[in]   radio   The handle to radio
 172  * @param[out]  state   The current state of the radio
 173  * @return @c 0 on success,
 174  *         otherwise a negative error value
 175  * @retval #RADIO_ERROR_NONE Successful
 176  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 177  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 178  */
 179 int  radio_get_state(radio_h radio, radio_state_e *state);
 180
 181 /**
 182  * @brief Starts playing the radio.
 183  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 184  * @param[in]   radio The handle to radio
 185  * @return @c 0 on success,
 186  *         otherwise a negative error value
 187  * @retval #RADIO_ERROR_NONE Successful
 188  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 189  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 190  * @retval #RADIO_ERROR_SOUND_POLICY Sound policy error
 191  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 192  * @pre The radio state must be set to #RADIO_STATE_READY by calling radio_create().
 193  * @post The radio state will be #RADIO_STATE_PLAYING.
 194  * @see radio_stop()
 195  */
 196 int radio_start(radio_h radio);
 197
 198 /**
 199  * @brief Stops playing the radio.
 200  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 201  * @param[in]   radio The handle to radio
 202  * @return @c 0 on success,
 203  *         otherwise a negative error value
 204  * @retval #RADIO_ERROR_NONE Successful
 205  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
 206  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 207  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 208  * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
 209  * @post The radio state will be #RADIO_STATE_READY.
 210  * @see radio_start()
 211  * @see radio_scan_start()
 212  */
 213 int radio_stop(radio_h radio);
 214
 215 /**
 216  * @brief Seeks up the effective frequency of the radio, asynchronously.
 217  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 218  * @param[in]   radio The handle to radio
 219  * @param[in] callback  The callback function to register
 220  * @param[in] user_data The user data to be passed to the callback function
 221  * @return @c 0 on success,
 222  *         otherwise a negative error value
 223  * @retval #RADIO_ERROR_NONE Successful
 224  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 225  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 226  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 227  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 228  * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
 229  * @post It invokes radio_seek_completed_cb() when the seek completes.
 230  * @see radio_seek_down()
 231  */
 232 int radio_seek_up(radio_h radio,radio_seek_completed_cb callback, void *user_data );
 233
 234 /**
 235  * @brief Seeks down the effective frequency of the radio, asynchronously.
 236  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 237  * @param[in]   radio The handle to radio
 238  * @param[in] callback  The callback function to register
 239  * @param[in] user_data The user data to be passed to the callback function
 240  * @return @c 0 on success,
 241  *         otherwise a negative error value
 242  * @retval #RADIO_ERROR_NONE Successful
 243  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 244  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 245  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 246  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 247  * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
 248  * @post It invokes radio_seek_completed_cb() when the seek completes.
 249  * @see radio_seek_up()
 250  */
 251 int radio_seek_down(radio_h radio,radio_seek_completed_cb callback, void *user_data );
 252
 253 /**
 254  * @brief Sets the radio frequency.
 255  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 256  * @param[in]   radio The handle to radio
 257  * @param[in]   frequency The frequency to set [87500 ~ 108000] (kHz)
 258  * @return @c 0 on success,
 259  *         otherwise a negative error value
 260  * @retval #RADIO_ERROR_NONE Successful
 261  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 262  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 263  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 264  * @see radio_get_frequency()
 265  */
 266 int radio_set_frequency(radio_h radio, int frequency);
 267
 268 /**
 269  * @brief Gets the current frequency of the radio.
 270  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 271  * @param[in]   radio The handle to radio
 272  * @param[out]  frequency The current frequency [87500 ~ 108000] (kHz)
 273  * @return @c 0 on success,
 274  *         otherwise a negative error value
 275  * @retval #RADIO_ERROR_NONE Successful
 276  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 277  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 278  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 279  * @see radio_set_frequency()
 280  */
 281 int radio_get_frequency(radio_h radio, int *frequency);
 282
 283 /**
 284  * @brief Gets the current signal strength of the radio.
 285  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 286  * @param[in]   radio The handle to radio
 287  * @param[out]  strength The current signal strength [-128 ~ 128] (dBm)
 288  * @return @c 0 on success,
 289  *         otherwise a negative error value
 290  * @retval #RADIO_ERROR_NONE Successful
 291  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 292  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 293  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 294  */
 295 int radio_get_signal_strength(radio_h radio, int *strength);
 296
 297 /**
 298  * @brief Starts scanning radio signals, asynchronously
 299  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 300  * @param[in]   radio The handle to radio
 301  * @param[in] callback  The callback function to register
 302  * @param[in] user_data The user data to be passed to the callback function
 303  * @return @c 0 on success,
 304  *         otherwise a negative error value
 305  * @retval #RADIO_ERROR_NONE Successful
 306  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 307  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 308  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 309  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 310  * @pre The radio state must be set to #RADIO_STATE_READY by calling radio_create() or radio_stop().
 311  * @post The radio state will be #RADIO_STATE_SCANNING during a search. After the scan is completed, the radio state will be #RADIO_STATE_READY.
 312  * @post It invokes radio_scan_updated_cb() when the scan information updates.
 313  * @post It invokes radio_scan_completed_cb() when the scan completes, if you set a callback with radio_set_scan_completed_cb().
 314  * @see radio_scan_stop()
 315  * @see radio_set_scan_completed_cb()
 316  * @see radio_scan_completed_cb()
 317  */
 318 int radio_scan_start(radio_h radio, radio_scan_updated_cb callback, void *user_data);
 319
 320 /**
 321  * @brief Stops scanning radio signals, asynchronously.
 322  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 323  * @param[in]   radio The handle to radio
 324  * @param[in] callback  The callback function to register
 325  * @param[in] user_data The user data to be passed to the callback function
 326  * @return @c 0 on success,
 327  *         otherwise a negative error value
 328  * @retval #RADIO_ERROR_NONE Successful
 329  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
 330  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 331  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 332  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 333  * @pre The radio state must be set to #RADIO_STATE_SCANNING by calling radio_scan_start().
 334  * @post It invokes radio_scan_stopped_cb() when the scan stops.
 335  * @post The radio state will be #RADIO_STATE_READY.
 336  * @see radio_scan_start()
 337  */
 338 int radio_scan_stop(radio_h radio, radio_scan_stopped_cb callback, void *user_data);
 339
 340 /**
 341  * @brief Sets the radio's mute status.
 342  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 343  * @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.
 344  * @param[in]   radio The handle to radio
 345  * @param[in]   muted The new mute status: (@c true = mute, @c false = not muted)
 346  * @return @c 0 on success,
 347  *         otherwise a negative error value
 348  * @retval #RADIO_ERROR_NONE Successful
 349  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 350  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 351  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 352  * @see radio_is_muted()
 353  */
 354 int radio_set_mute(radio_h radio, bool muted);
 355
 356 /**
 357  * @brief Gets the radio's mute status.
 358  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 359  * @details If the mute status is @c true, no sounds are played. If @c false, sounds are played.
 360  * @param[in]   radio The handle to radio
 361  * @param[out]  muted  The current mute status: (@c true = mute, @c false = not muted)
 362  * @return @c 0 on success,
 363  *         otherwise a negative error value
 364  * @retval #RADIO_ERROR_NONE Successful
 365  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 366  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 367  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 368  * @see radio_set_mute()
 369  */
 370 int radio_is_muted(radio_h radio, bool *muted);
 371
 372 /**
 373  * @brief Registers a callback function to be invoked when the scan finishes.
 374  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 375  * @param[in] radio     The handle to radio
 376  * @param[in] callback  The callback function to register
 377  * @param[in] user_data The user data to be passed to the callback function
 378  * @return @c 0 on success,
 379  *         otherwise a negative error value
 380  * @retval #RADIO_ERROR_NONE Successful
 381  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 382  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 383  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 384  * @post radio_scan_completed_cb() will be invoked.
 385  * @see radio_unset_scan_completed_cb()
 386  * @see radio_scan_completed_cb()
 387  */
 388 int radio_set_scan_completed_cb(radio_h radio, radio_scan_completed_cb callback, void *user_data);
 389
 390 /**
 391  * @brief       Unregisters the callback function.
 392  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 393  * @param[in] radio The handle to radio
 394  * @return @c 0 on success,
 395  *         otherwise a negative error value
 396  * @retval #RADIO_ERROR_NONE Successful
 397  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 398  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 399  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 400  * @see radio_set_scan_completed_cb()
 401  */
 402 int radio_unset_scan_completed_cb(radio_h radio);
 403
 404 /**
 405  * @brief Registers a callback function to be invoked when the radio is interrupted.
 406  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 407  * @param[in] radio     The handle to radio
 408  * @param[in] callback  The callback function to register
 409  * @param[in] user_data The user data to be passed to the callback function
 410  * @return @c 0 on success,
 411  *         otherwise a negative error value
 412  * @retval #RADIO_ERROR_NONE Successful
 413  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 414  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 415  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 416  * @post  radio_interrupted_cb() will be invoked.
 417  * @see radio_unset_interrupted_cb()
 418  * @see #radio_interrupted_code_e
 419  * @see radio_interrupted_cb()
 420  */
 421 int radio_set_interrupted_cb(radio_h radio, radio_interrupted_cb callback, void *user_data);
 422
 423 /**
 424  * @brief Unregisters the callback function.
 425  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 426  * @param[in] radio The handle to radio
 427  * @return @c 0 on success,
 428  *         otherwise a negative error value
 429  * @retval #RADIO_ERROR_NONE Successful
 430  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 431  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 432  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 433  * @see radio_set_interrupted_cb()
 434  */
 435 int radio_unset_interrupted_cb(radio_h radio);
 436
 437 /**
 438  * @}
 439  */
 440
 441 #ifdef __cplusplus
 442 }
 443 #endif
 444
 445 #endif /* __TIZEN_MEDIA_RADIO_H__ */