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         RADIO_STATE_READY,                      /**< Ready to play or scan */
  49         RADIO_STATE_PLAYING,            /**< Playing the audio from the tuner */
  50         RADIO_STATE_SCANNING,           /**< Scanning/Searching for the next station signal that starts from a given starting frequency */
  51 } radio_state_e;
  52
  53 /**
  54  * @brief Enumeration of error codes for the radio.
  55  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  56  */
  57 typedef enum {
  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           = TIZEN_ERROR_RADIO | 0x01  ,                                       /**< Invalid state */
  63         RADIO_ERROR_SOUND_POLICY            = TIZEN_ERROR_RADIO | 0x02  ,                                       /**< Sound policy error */
  64         RADIO_ERROR_NO_ANTENNA                  = TIZEN_ERROR_RADIO | 0x03 ,                             /**< No Antenna error (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
  65         RADIO_ERROR_PERMISSION_DENIED   = TIZEN_ERROR_PERMISSION_DENIED,                        /**< Permission denied */
  66         RADIO_ERROR_NOT_SUPPORTED   = TIZEN_ERROR_NOT_SUPPORTED,                                        /**< Not supported */
  67 } radio_error_e;
  68
  69 /**
  70  * @brief Enumeration of radio interrupted type.
  71  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  72  */
  73 typedef enum {
  74         RADIO_INTERRUPTED_BY_RESOURCE_CONFLICT = 4,             /**< Interrupted by a resource conflict */
  75 } radio_interrupted_code_e;
  76
  77 /**
  78  * @brief  Called when the scan information is updated.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80  * @param[in] frequency  The tuned radio frequency [87500 ~ 108000] (kHz)
  81  * @param[in] user_data  The user data passed from the callback registration function
  82  * @pre It will be invoked by radio_scan_start().
  83  * @see radio_scan_start()
  84  */
  85 typedef void (*radio_scan_updated_cb)(int frequency, void *user_data);
  86
  87 /**
  88  * @brief  Called when the radio scan is stopped.
  89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  90  * @param[in] user_data  The user data passed from the callback registration function
  91  * @pre It will be invoked when the scan is stopped by radio_scan_stop().
  92  * @see radio_scan_stop()
  93  */
  94 typedef void (*radio_scan_stopped_cb)(void *user_data);
  95
  96 /**
  97  * @brief  Called when the radio scan is completed.
  98  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  99  * @param[in] user_data  The user data passed from the callback registration function
 100  * @pre It will be invoked when the scan is completed by registering 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  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 110  * @param[in] frequency  The current frequency [87500 ~ 108000] (kHz)
 111  * @param[in] user_data  The user data passed from the callback registration function
 112  * @pre It will be invoked when the radio seek is completed by registering this callback using radio_seek_up() or radio_seek_down().
 113  * @see radio_seek_up()
 114  * @see radio_seek_down()
 115  */
 116 typedef void (*radio_seek_completed_cb)(int frequency, void *user_data);
 117
 118 /**
 119  * @brief  Called when the radio is interrupted.
 120  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 121  * @param[in] code      The interrupted error code
 122  * @param[in] user_data The user data passed from the callback registration function
 123  * @see radio_set_interrupted_cb()
 124  * @see radio_unset_interrupted_cb()
 125  */
 126 typedef void (*radio_interrupted_cb)(radio_interrupted_code_e code, void *user_data);
 127
 128 /**
 129  * @brief Creates a radio handle.
 130  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 131  * @remarks You must release @a radio using radio_destroy().
 132  * @param[out] radio A new handle to radio
 133  * @return @c 0 on success,
 134  *         otherwise a negative error value
 135  * @retval #RADIO_ERROR_NONE Successful
 136  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 137  * @retval #RADIO_ERROR_OUT_OF_MEMORY Out of memory
 138  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 139  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 140  * @see radio_destroy()
 141  */
 142 int radio_create(radio_h *radio);
 143
 144 /**
 145  * @brief Destroys the radio handle and releases all its resources.
 146  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 147  * @remarks To completely shutdown the radio operation, call this function with a valid radio handle.
 148  *
 149  * @param[in] radio The handle to radio to be destroyed
 150  * @return @c 0 on success,
 151  *         otherwise a negative error value
 152  * @retval #RADIO_ERROR_NONE Successful
 153  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 154  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 155  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 156  * @see radio_create()
 157  */
 158 int radio_destroy(radio_h radio);
 159
 160 /**
 161  * @brief Gets the radio's current state.
 162  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 163  * @param[in]  radio The handle to radio
 164  * @param[out] state The current state of the radio
 165  * @return @c 0 on success,
 166  *         otherwise a negative error value
 167  * @retval #RADIO_ERROR_NONE Successful
 168  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 169  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 170  */
 171 int  radio_get_state(radio_h radio, radio_state_e *state);
 172
 173 /**
 174  * @brief Starts playing the radio.
 175  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 176  * @param[in] radio The handle to radio
 177  * @return @c 0 on success,
 178  *         otherwise a negative error value
 179  * @retval #RADIO_ERROR_NONE Successful
 180  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 181  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 182  * @retval #RADIO_ERROR_SOUND_POLICY Sound policy error
 183  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 184  * @retval #RADIO_ERROR_NO_ANTENNA No Antenna error
 185  * @pre The radio state must be set to #RADIO_STATE_READY by calling radio_create().
 186  * @post The radio state will be #RADIO_STATE_PLAYING.
 187  * @see radio_stop()
 188  */
 189 int radio_start(radio_h radio);
 190
 191 /**
 192  * @brief Stops playing the radio.
 193  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 194  * @param[in] radio The handle to radio
 195  * @return @c 0 on success,
 196  *         otherwise a negative error value
 197  * @retval #RADIO_ERROR_NONE Successful
 198  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
 199  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 200  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 201  * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
 202  * @post The radio state will be #RADIO_STATE_READY.
 203  * @see radio_start()
 204  * @see radio_scan_start()
 205  */
 206 int radio_stop(radio_h radio);
 207
 208 /**
 209  * @brief Seeks up the effective frequency of the radio, asynchronously.
 210  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 211  * @param[in] radio     The handle to radio
 212  * @param[in] callback  The callback function to register
 213  * @param[in] user_data The user data to be passed to the callback function
 214  * @return @c 0 on success,
 215  *         otherwise a negative error value
 216  * @retval #RADIO_ERROR_NONE Successful
 217  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 218  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 219  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 220  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 221  * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
 222  * @post It invokes radio_seek_completed_cb() when the seek completes.
 223  * @see radio_seek_down()
 224  */
 225 int radio_seek_up(radio_h radio, radio_seek_completed_cb callback, void *user_data);
 226
 227 /**
 228  * @brief Seeks down the effective frequency of the radio, asynchronously.
 229  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 230  * @param[in] radio     The handle to radio
 231  * @param[in] callback  The callback function to register
 232  * @param[in] user_data The user data to be passed to the callback function
 233  * @return @c 0 on success,
 234  *         otherwise a negative error value
 235  * @retval #RADIO_ERROR_NONE Successful
 236  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 237  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 238  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 239  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 240  * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
 241  * @post It invokes radio_seek_completed_cb() when the seek completes.
 242  * @see radio_seek_up()
 243  */
 244 int radio_seek_down(radio_h radio, radio_seek_completed_cb callback, void *user_data);
 245
 246 /**
 247  * @brief Sets the radio frequency.
 248  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 249  * @param[in] radio     The handle to radio
 250  * @param[in] frequency The frequency to set [87500 ~ 108000] (kHz)
 251  * @return @c 0 on success,
 252  *         otherwise a negative error value
 253  * @retval #RADIO_ERROR_NONE Successful
 254  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 255  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 256  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 257  * @see radio_get_frequency()
 258  */
 259 int radio_set_frequency(radio_h radio, int frequency);
 260
 261 /**
 262  * @brief Gets the current frequency of the radio.
 263  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 264  * @param[in]  radio     The handle to radio
 265  * @param[out] frequency The current frequency [87500 ~ 108000] (kHz)
 266  * @return @c 0 on success,
 267  *         otherwise a negative error value
 268  * @retval #RADIO_ERROR_NONE Successful
 269  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 270  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 271  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 272  * @see radio_set_frequency()
 273  */
 274 int radio_get_frequency(radio_h radio, int *frequency);
 275
 276 /**
 277  * @brief Gets the current signal strength of the radio.
 278  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 279  * @param[in]  radio    The handle to radio
 280  * @param[out] strength The current signal strength [-128 ~ 128] (dBm)
 281  * @return @c 0 on success,
 282  *         otherwise a negative error value
 283  * @retval #RADIO_ERROR_NONE Successful
 284  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 285  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 286  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 287  */
 288 int radio_get_signal_strength(radio_h radio, int *strength);
 289
 290 /**
 291  * @brief Starts scanning radio signals, asynchronously.
 292  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 293  * @param[in] radio     The handle to radio
 294  * @param[in] callback  The callback function to register
 295  * @param[in] user_data The user data to be passed to the callback function
 296  * @return @c 0 on success,
 297  *         otherwise a negative error value
 298  * @retval #RADIO_ERROR_NONE Successful
 299  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 300  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 301  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 302  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 303  * @pre The radio state must be set to #RADIO_STATE_READY or #RADIO_STATE_PLAYING.
 304  * @post The radio state will be #RADIO_STATE_SCANNING during a search. After the scan is completed, the radio state will be set back to the state from before the function call(#RADIO_STATE_READY or #RADIO_STATE_PLAYING).
 305  * @post It invokes radio_scan_updated_cb() when the scan information updates.
 306  * @post It invokes radio_scan_completed_cb() when the scan completes, if you set a callback with radio_set_scan_completed_cb().
 307  * @see radio_scan_stop()
 308  * @see radio_set_scan_completed_cb()
 309  * @see radio_scan_completed_cb()
 310  */
 311 int radio_scan_start(radio_h radio, radio_scan_updated_cb callback, void *user_data);
 312
 313 /**
 314  * @brief Stops scanning radio signals, asynchronously.
 315  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 316  * @param[in] radio     The handle to radio
 317  * @param[in] callback  The callback function to register
 318  * @param[in] user_data The user data to be passed to the callback function
 319  * @return @c 0 on success,
 320  *         otherwise a negative error value
 321  * @retval #RADIO_ERROR_NONE Successful
 322  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
 323  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 324  * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
 325  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 326  * @pre The radio state must be set to #RADIO_STATE_SCANNING by calling radio_scan_start().
 327  * @post It invokes radio_scan_stopped_cb() when the scan stops.
 328  * @post After the scan stopped, the radio state will be set back to the state from before the radio_scan_start() function call(#RADIO_STATE_READY or #RADIO_STATE_PLAYING).
 329  * @see radio_scan_start()
 330  */
 331 int radio_scan_stop(radio_h radio, radio_scan_stopped_cb callback, void *user_data);
 332
 333 /**
 334  * @brief Sets the radio's mute status.
 335  * @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.
 336  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 337  * @param[in] radio The handle to radio
 338  * @param[in] muted The new mute status: (@c true = mute, @c false = not muted)
 339  * @return @c 0 on success,
 340  *         otherwise a negative error value
 341  * @retval #RADIO_ERROR_NONE Successful
 342  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 343  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 344  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 345  * @see radio_is_muted()
 346  */
 347 int radio_set_mute(radio_h radio, bool muted);
 348
 349 /**
 350  * @brief Gets the radio's mute status.
 351  * @details If the mute status is @c true, no sounds are played. If @c false, sounds are played.
 352  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 353  * @param[in]  radio The handle to radio
 354  * @param[out] muted The current mute status: (@c true = mute, @c false = not muted)
 355  * @return @c 0 on success,
 356  *         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  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 361  * @see radio_set_mute()
 362  */
 363 int radio_is_muted(radio_h radio, bool *muted);
 364
 365 /**
 366  * @brief Sets a callback function to be invoked when the scan finishes.
 367  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 368  * @param[in] radio     The handle to radio
 369  * @param[in] callback  The callback function to register
 370  * @param[in] user_data The user data to be passed to the callback function
 371  * @return @c 0 on success,
 372  *         otherwise a negative error value
 373  * @retval #RADIO_ERROR_NONE Successful
 374  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 375  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 376  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 377  * @post radio_scan_completed_cb() will be invoked.
 378  * @see radio_unset_scan_completed_cb()
 379  * @see radio_scan_completed_cb()
 380  */
 381 int radio_set_scan_completed_cb(radio_h radio, radio_scan_completed_cb callback, void *user_data);
 382
 383 /**
 384  * @brief Unsets the scan completed callback function.
 385  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 386  * @param[in] radio The handle to radio
 387  * @return @c 0 on success,
 388  *         otherwise a negative error value
 389  * @retval #RADIO_ERROR_NONE Successful
 390  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 391  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 392  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 393  * @see radio_set_scan_completed_cb()
 394  */
 395 int radio_unset_scan_completed_cb(radio_h radio);
 396
 397 /**
 398  * @brief Sets a callback function to be invoked when the radio is interrupted.
 399  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 400  * @param[in] radio     The handle to radio
 401  * @param[in] callback  The callback function to register
 402  * @param[in] user_data The user data to be passed to the callback function
 403  * @return @c 0 on success,
 404  *         otherwise a negative error value
 405  * @retval #RADIO_ERROR_NONE Successful
 406  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 407  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 408  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 409  * @post  radio_interrupted_cb() will be invoked.
 410  * @see radio_unset_interrupted_cb()
 411  * @see #radio_interrupted_code_e
 412  * @see radio_interrupted_cb()
 413  */
 414 int radio_set_interrupted_cb(radio_h radio, radio_interrupted_cb callback, void *user_data);
 415
 416 /**
 417  * @brief Unsets the interrupted callback function.
 418  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 419  * @param[in] radio The handle to radio
 420  * @return @c 0 on success,
 421  *         otherwise a negative error value
 422  * @retval #RADIO_ERROR_NONE Successful
 423  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 424  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 425  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 426  * @see radio_set_interrupted_cb()
 427  */
 428 int radio_unset_interrupted_cb(radio_h radio);
 429
 430 /**
 431  * @brief Gets the min, max frequency of the region.
 432  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 433  * @param[in]  radio    The handle to radio
 434  * @param[out] min_freq The min frequency [87500 ~ 108000] (kHz)
 435  * @param[out] max_freq The max frequency [87500 ~ 108000] (kHz)
 436  * @return @c 0 on success,
 437  *         otherwise a negative error value
 438  * @retval #RADIO_ERROR_NONE Successful
 439  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 440  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 441  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 442  */
 443 int radio_get_frequency_range(radio_h radio, int *min_freq, int *max_freq);
 444
 445 /**
 446  * @brief Gets channel spacing.
 447  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 448  * @param[in]   radio           The handle to radio
 449  * @param[out]  channel_spacing The channel spacing value
 450  * @return @c 0 on success,
 451  *         otherwise a negative error value
 452  * @retval #RADIO_ERROR_NONE Successful
 453  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 454  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 455  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 456  */
 457 int radio_get_channel_spacing(radio_h radio, int *channel_spacing);
 458
 459 /**
 460  * @brief Sets the radio's volume.
 461  * @details  Setting this volume adjusts the radio's instance volume, not the system volume.
 462  *           The valid range is from 0 to 1.0, inclusive (1.0 = 100%). Default value is 1.0.
 463  *           To change system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
 464  *           Finally, it does not support to set other value into each channel currently.
 465  * @since_tizen 3.0
 466  * @param[in] radio  The handle to radio
 467  * @param[in] volume The volume to set [0.0 ~ 1.0](1.0 = 100%)
 468  * @return @c 0 on success,
 469  *         otherwise a negative error value
 470  * @retval #RADIO_ERROR_NONE Successful
 471  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 472  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 473  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 474  * @see radio_get_volume()
 475  */
 476 int radio_set_volume(radio_h radio, float volume);
 477
 478 /**
 479  * @brief Gets the radio's current volume.
 480  * @details The range of @a volume is from @c 0 to @c 1.0, inclusive (1.0 = 100%).
 481  *          This function gets the radio volume, not the system volume.
 482  *          To get the system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
 483  * @since_tizen 3.0
 484  * @param[in]  radio  The handle to radio
 485  * @param[out] volume The current volume [0.0 ~ 1.0](1.0 = 100%)
 486  * @return @c 0 on success,
 487  *         otherwise a negative error value
 488  * @retval #RADIO_ERROR_NONE Successful
 489  * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 490  * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
 491  * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
 492  * @see radio_set_volume()
 493  */
 494 int radio_get_volume(radio_h radio, float *volume);
 495
 496 /**
 497  * @}
 498  */
 499
 500 #ifdef __cplusplus
 501 }
 502 #endif
 503
 504 #endif /* __TIZEN_MEDIA_RADIO_H__ */