2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __TIZEN_MEDIA_RADIO_H__
18 #define __TIZEN_MEDIA_RADIO_H__
28 * @brief This file contains the radio API.
29 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
33 * @addtogroup CAPI_MEDIA_RADIO_MODULE
38 * @brief Radio type handle.
39 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
41 typedef struct radio_s *radio_h;
44 * @brief Enumeration of radio state.
45 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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 */
54 * @brief Enumeration of error codes for the radio.
55 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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 */
70 * @brief Enumeration of radio interrupted type.
71 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
74 RADIO_INTERRUPTED_COMPLETED = 0, /**< Interrupt completed */
75 RADIO_INTERRUPTED_BY_MEDIA, /**< Interrupted by a non-resumable media application */
76 RADIO_INTERRUPTED_BY_CALL, /**< Interrupted by an incoming call */
77 RADIO_INTERRUPTED_BY_EARJACK_UNPLUG, /**< Interrupted by unplugging headphones */
78 RADIO_INTERRUPTED_BY_RESOURCE_CONFLICT, /**< Interrupted by a resource conflict */
79 RADIO_INTERRUPTED_BY_ALARM, /**< Interrupted by an alarm */
80 RADIO_INTERRUPTED_BY_EMERGENCY, /**< Interrupted by an emergency */
81 RADIO_INTERRUPTED_BY_RESUMABLE_MEDIA, /**< Interrupted by a resumable media application */
82 RADIO_INTERRUPTED_BY_NOTIFICATION, /**< Interrupted by a notification */
83 } radio_interrupted_code_e;
86 * @brief Called when the scan information is updated.
87 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
88 * @param[in] frequency The tuned radio frequency [87500 ~ 108000] (kHz)
89 * @param[in] user_data The user data passed from the callback registration function
90 * @pre It will be invoked by radio_scan_start().
91 * @see radio_scan_start()
93 typedef void (*radio_scan_updated_cb)(int frequency, void *user_data);
96 * @brief Called when the radio scan is stopped.
97 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
98 * @param[in] user_data The user data passed from the callback registration function
99 * @pre It will be invoked when the scan is stopped by radio_scan_stop().
100 * @see radio_scan_stop()
102 typedef void (*radio_scan_stopped_cb)(void *user_data);
105 * @brief Called when the radio scan is completed.
106 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
107 * @param[in] user_data The user data passed from the callback registration function
108 * @pre It will be invoked when the scan is completed by registering this callback using radio_set_scan_completed_cb().
109 * @see radio_scan_start()
110 * @see radio_set_scan_completed_cb()
111 * @see radio_unset_scan_completed_cb()
113 typedef void (*radio_scan_completed_cb)(void *user_data);
116 * @brief Called when the radio seek is completed.
117 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
118 * @param[in] frequency The current frequency [87500 ~ 108000] (kHz)
119 * @param[in] user_data The user data passed from the callback registration function
120 * @pre It will be invoked when the radio seek is completed by registering this callback using radio_seek_up() or radio_seek_down().
121 * @see radio_seek_up()
122 * @see radio_seek_down()
124 typedef void (*radio_seek_completed_cb)(int frequency, void *user_data);
127 * @brief Called when the radio is interrupted.
128 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
129 * @param[in] error_code The interrupted error code
130 * @param[in] user_data The user data passed from the callback registration function
131 * @see radio_set_interrupted_cb()
132 * @see radio_unset_interrupted_cb()
134 typedef void (*radio_interrupted_cb)(radio_interrupted_code_e code, void *user_data);
137 * @brief Creates a radio handle.
138 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
139 * @remarks You must release @a radio using radio_destroy().
140 * @param[out] radio A new handle to radio
141 * @retval #RADIO_ERROR_NONE Successful
142 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
143 * @retval #RADIO_ERROR_OUT_OF_MEMORY Out of memory
144 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
145 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
146 * @see radio_destroy()
148 int radio_create(radio_h *radio);
151 * @brief Destroys the radio handle and releases all its resources.
152 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
153 * @remarks To completely shutdown the radio operation, call this function with a valid radio handle.
155 * @param[in] radio The handle to radio to be destroyed
156 * @return @c 0 on success,
157 * otherwise a negative error value
158 * @retval #RADIO_ERROR_NONE Successful
159 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
160 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
161 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
162 * @see radio_create()
164 int radio_destroy(radio_h radio);
167 * @brief Gets the radio's current state.
168 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
169 * @param[in] radio The handle to radio
170 * @param[out] state The current state of the radio
171 * @return @c 0 on success,
172 * otherwise a negative error value
173 * @retval #RADIO_ERROR_NONE Successful
174 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
175 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
177 int radio_get_state(radio_h radio, radio_state_e *state);
180 * @brief Starts playing the radio.
181 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
182 * @param[in] radio The handle to radio
183 * @return @c 0 on success,
184 * otherwise a negative error value
185 * @retval #RADIO_ERROR_NONE Successful
186 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
187 * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
188 * @retval #RADIO_ERROR_SOUND_POLICY Sound policy error
189 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
190 * @retval #RADIO_ERROR_NO_ANTENNA No Antenna error
191 * @pre The radio state must be set to #RADIO_STATE_READY by calling radio_create().
192 * @post The radio state will be #RADIO_STATE_PLAYING.
195 int radio_start(radio_h radio);
198 * @brief Stops playing the radio.
199 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
200 * @param[in] radio The handle to radio
201 * @return @c 0 on success,
202 * otherwise a negative error value
203 * @retval #RADIO_ERROR_NONE Successful
204 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
205 * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
206 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
207 * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
208 * @post The radio state will be #RADIO_STATE_READY.
210 * @see radio_scan_start()
212 int radio_stop(radio_h radio);
215 * @brief Seeks up the effective frequency of the radio, asynchronously.
216 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
217 * @param[in] radio The handle to radio
218 * @param[in] callback The callback function to register
219 * @param[in] user_data The user data to be passed to the callback function
220 * @return @c 0 on success,
221 * otherwise a negative error value
222 * @retval #RADIO_ERROR_NONE Successful
223 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
224 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
225 * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
226 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
227 * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
228 * @post It invokes radio_seek_completed_cb() when the seek completes.
229 * @see radio_seek_down()
231 int radio_seek_up(radio_h radio, radio_seek_completed_cb callback, void *user_data);
234 * @brief Seeks down the effective frequency of the radio, asynchronously.
235 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
236 * @param[in] radio The handle to radio
237 * @param[in] callback The callback function to register
238 * @param[in] user_data The user data to be passed to the callback function
239 * @return @c 0 on success,
240 * otherwise a negative error value
241 * @retval #RADIO_ERROR_NONE Successful
242 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
243 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
244 * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
245 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
246 * @pre The radio state must be set to #RADIO_STATE_PLAYING by calling radio_start().
247 * @post It invokes radio_seek_completed_cb() when the seek completes.
248 * @see radio_seek_up()
250 int radio_seek_down(radio_h radio, radio_seek_completed_cb callback, void *user_data);
253 * @brief Sets the radio frequency.
254 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
255 * @param[in] radio The handle to radio
256 * @param[in] frequency The frequency to set [87500 ~ 108000] (kHz)
257 * @return @c 0 on success,
258 * otherwise a negative error value
259 * @retval #RADIO_ERROR_NONE Successful
260 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
261 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
262 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
263 * @see radio_get_frequency()
265 int radio_set_frequency(radio_h radio, int frequency);
268 * @brief Gets the current frequency of the radio.
269 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
270 * @param[in] radio The handle to radio
271 * @param[out] frequency The current frequency [87500 ~ 108000] (kHz)
272 * @return @c 0 on success,
273 * otherwise a negative error value
274 * @retval #RADIO_ERROR_NONE Successful
275 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
276 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
277 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
278 * @see radio_set_frequency()
280 int radio_get_frequency(radio_h radio, int *frequency);
283 * @brief Gets the current signal strength of the radio.
284 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
285 * @param[in] radio The handle to radio
286 * @param[out] strength The current signal strength [-128 ~ 128] (dBm)
287 * @return @c 0 on success,
288 * otherwise a negative error value
289 * @retval #RADIO_ERROR_NONE Successful
290 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
291 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
292 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
294 int radio_get_signal_strength(radio_h radio, int *strength);
297 * @brief Starts scanning radio signals, asynchronously
298 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
299 * @param[in] radio The handle to radio
300 * @param[in] callback The callback function to register
301 * @param[in] user_data The user data to be passed to the callback function
302 * @return @c 0 on success,
303 * 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 * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
308 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
309 * @pre The radio state must be set to #RADIO_STATE_READY by calling radio_create() or radio_stop().
310 * @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.
311 * @post It invokes radio_scan_updated_cb() when the scan information updates.
312 * @post It invokes radio_scan_completed_cb() when the scan completes, if you set a callback with radio_set_scan_completed_cb().
313 * @see radio_scan_stop()
314 * @see radio_set_scan_completed_cb()
315 * @see radio_scan_completed_cb()
317 int radio_scan_start(radio_h radio, radio_scan_updated_cb callback, void *user_data);
320 * @brief Stops scanning radio signals, asynchronously.
321 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
322 * @param[in] radio The handle to radio
323 * @param[in] callback The callback function to register
324 * @param[in] user_data The user data to be passed to the callback function
325 * @return @c 0 on success,
326 * otherwise a negative error value
327 * @retval #RADIO_ERROR_NONE Successful
328 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
329 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
330 * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
331 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
332 * @pre The radio state must be set to #RADIO_STATE_SCANNING by calling radio_scan_start().
333 * @post It invokes radio_scan_stopped_cb() when the scan stops.
334 * @post The radio state will be #RADIO_STATE_READY.
335 * @see radio_scan_start()
337 int radio_scan_stop(radio_h radio, radio_scan_stopped_cb callback, void *user_data);
340 * @brief Sets the radio's mute status.
341 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
342 * @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.
343 * @param[in] radio The handle to radio
344 * @param[in] muted The new mute status: (@c true = mute, @c false = not muted)
345 * @return @c 0 on success,
346 * otherwise a negative error value
347 * @retval #RADIO_ERROR_NONE Successful
348 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
349 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
350 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
351 * @see radio_is_muted()
353 int radio_set_mute(radio_h radio, bool muted);
356 * @brief Gets the radio's mute status.
357 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
358 * @details If the mute status is @c true, no sounds are played. If @c false, sounds are played.
359 * @param[in] radio The handle to radio
360 * @param[out] muted The current mute status: (@c true = mute, @c false = not muted)
361 * @return @c 0 on success,
362 * otherwise a negative error value
363 * @retval #RADIO_ERROR_NONE Successful
364 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
365 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
366 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
367 * @see radio_set_mute()
369 int radio_is_muted(radio_h radio, bool *muted);
372 * @brief Registers a callback function to be invoked when the scan finishes.
373 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
374 * @param[in] radio The handle to radio
375 * @param[in] callback The callback function to register
376 * @param[in] user_data The user data to be passed to the callback function
377 * @return @c 0 on success,
378 * otherwise a negative error value
379 * @retval #RADIO_ERROR_NONE Successful
380 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
381 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
382 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
383 * @post radio_scan_completed_cb() will be invoked.
384 * @see radio_unset_scan_completed_cb()
385 * @see radio_scan_completed_cb()
387 int radio_set_scan_completed_cb(radio_h radio, radio_scan_completed_cb callback, void *user_data);
390 * @brief Unregisters the callback function.
391 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
392 * @param[in] radio The handle to radio
393 * @return @c 0 on success,
394 * otherwise a negative error value
395 * @retval #RADIO_ERROR_NONE Successful
396 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
397 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
398 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
399 * @see radio_set_scan_completed_cb()
401 int radio_unset_scan_completed_cb(radio_h radio);
404 * @brief Registers a callback function to be invoked when the radio is interrupted.
405 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
406 * @param[in] radio The handle to radio
407 * @param[in] callback The callback function to register
408 * @param[in] user_data The user data to be passed to the callback function
409 * @return @c 0 on success,
410 * otherwise a negative error value
411 * @retval #RADIO_ERROR_NONE Successful
412 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
413 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
414 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
415 * @post radio_interrupted_cb() will be invoked.
416 * @see radio_unset_interrupted_cb()
417 * @see #radio_interrupted_code_e
418 * @see radio_interrupted_cb()
420 int radio_set_interrupted_cb(radio_h radio, radio_interrupted_cb callback, void *user_data);
423 * @brief Unregisters the callback function.
424 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
425 * @param[in] radio The handle to radio
426 * @return @c 0 on success,
427 * otherwise a negative error value
428 * @retval #RADIO_ERROR_NONE Successful
429 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
430 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
431 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
432 * @see radio_set_interrupted_cb()
434 int radio_unset_interrupted_cb(radio_h radio);
437 * @brief Gets the min, max frequency of the region.
438 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
439 * @param[in] radio The handle to radio
440 * @param[out] min_freq The min frequency [87500 ~ 108000] (kHz)
441 * @param[out] max_freq The max frequency [87500 ~ 108000] (kHz)
442 * @return @c 0 on success,
443 * otherwise a negative error value
444 * @retval #RADIO_ERROR_NONE Successful
445 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
446 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
447 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
449 int radio_get_frequency_range(radio_h radio, int *min_freq, int *max_freq);
452 * @brief Gets channel spacing.
453 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
454 * @param[in] radio The handle to radio
455 * @param[out] channel_spacing The channel spacing value
456 * @return @c 0 on success,
457 * otherwise a negative error value
458 * @retval #RADIO_ERROR_NONE Successful
459 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
460 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
461 * @retval #RADIO_ERROR_NOT_SUPPORTED Not supported
463 int radio_get_channel_spacing(radio_h radio, int *channel_spacing);
474 #endif /* __TIZEN_MEDIA_RADIO_H__ */