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__
26 #define RADIO_ERROR_CLASS TIZEN_ERROR_MULTIMEDIA_CLASS | 0x70
30 * @brief This file contains the radio API.
34 * @addtogroup CAPI_MEDIA_RADIO_MODULE
39 * @brief Radio handle type.
41 typedef struct radio_s *radio_h;
44 * @brief Enumerations of radio state
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 */
54 * @brief Error codes for radio
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 */
67 * @brief Enumerations of radio interrupted type
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;
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()
87 typedef void (*radio_scan_updated_cb)(int frequency, void *user_data);
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()
95 typedef void (*radio_scan_stopped_cb)(void *user_data);
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()
105 typedef void (*radio_scan_completed_cb)(void *user_data);
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()
115 typedef void (*radio_seek_completed_cb)(int frequency, void *user_data);
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()
124 typedef void (*radio_interrupted_cb)(radio_interrupted_code_e code, void *user_data);
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()
136 int radio_create(radio_h *radio);
139 * @brief Destroys the radio handle and releases all its resources.
141 * @remarks To completely shutdown radio operation, call this function with a valid radio handle.
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()
150 int radio_destroy(radio_h radio);
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
160 int radio_get_state(radio_h radio, radio_state_e *state);
163 * @brief Starts playing radio.
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.
175 int radio_start(radio_h radio);
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.
187 * @see radio_scan_start()
189 int radio_stop(radio_h radio);
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()
205 int radio_seek_up(radio_h radio,radio_seek_completed_cb callback, void *user_data );
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()
221 int radio_seek_down(radio_h radio,radio_seek_completed_cb callback, void *user_data );
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()
233 int radio_set_frequency(radio_h radio, int frequency);
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()
245 int radio_get_frequency(radio_h radio, int *frequency);
248 * @brief Gets the current signal strength of radio.
249 * @param[in] radio The handle to radio
250 * @param[out] strength The current signal strength [0 ~ 65535] (dbuV)
251 * @return 0 on success, otherwise a negative error value.
252 * @retval #RADIO_ERROR_NONE Successful
253 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
254 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
256 int radio_get_signal_strength(radio_h radio, int *strength);
259 * @brief Starts scanning radio signals, asynchronously
261 * @param[in] radio The handle to radio
262 * @param[in] callback The callback function to register
263 * @param[in] user_data The user data to be passed to the callback function
264 * @return 0 on success, otherwise a negative error value.
265 * @retval #RADIO_ERROR_NONE Successful
266 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
267 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
268 * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
269 * @pre The radio state must be #RADIO_STATE_READY by either radio_create() or radio_stop().
270 * @post The radio state will be #RADIO_STATE_SCANNING during searching. After scan is completed, radio state will be #RADIO_STATE_READY.
271 * @post It invokes radio_scan_updated_cb() when the scan information updates.
272 * @post It invokes radio_scan_completed_cb() when scan completes, if you set a callback with radio_set_scan_completed_cb().
273 * @see radio_scan_stop()
274 * @see radio_set_scan_completed_cb()
275 * @see radio_scan_completed_cb()
277 int radio_scan_start(radio_h radio, radio_scan_updated_cb callback, void *user_data);
280 * @brief Stops scanning radio signals, asynchronously.
281 * @param[in] radio The handle to radio
282 * @param[in] callback The callback function to register
283 * @param[in] user_data The user data to be passed to the callback function
284 * @return 0 on success, otherwise a negative error value.
285 * @retval #RADIO_ERROR_NONE Successful
286 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid state
287 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
288 * @retval #RADIO_ERROR_INVALID_STATE Invalid radio state
289 * @pre The radio state must be #RADIO_STATE_SCANNING by radio_scan_start().
290 * @post It invokes radio_scan_stopped_cb() when the scan stops.
291 * @post The radio state will be #RADIO_STATE_READY.
292 * @see radio_scan_start()
294 int radio_scan_stop(radio_h radio, radio_scan_stopped_cb callback, void *user_data);
297 * @brief Sets the radio's mute status.
298 * @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.
299 * @param[in] radio The handle to radio
300 * @param[in] muted New mute status: (@c true = mute, @c false = not muted)
301 * @return 0 on success, otherwise a negative error value.
302 * @retval #RADIO_ERROR_NONE Successful
303 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
304 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
305 * @see radio_is_muted()
307 int radio_set_mute(radio_h radio, bool muted);
310 * @brief Gets the radio's mute status.
311 * @details If the mute status is @c true, no sounds are played. If @c false, sounds are played.
312 * @param[in] radio The handle to radio
313 * @param[out] muted The current mute status: (@c true = mute, @c false = not muted)
314 * @return 0 on success, otherwise a negative error value.
315 * @retval #RADIO_ERROR_NONE Successful
316 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
317 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
318 * @see radio_set_mute()
320 int radio_is_muted(radio_h radio, bool *muted);
323 * @brief Registers a callback function to be invoked when the scan finishes.
324 * @param[in] radio The handle to radio
325 * @param[in] callback The callback function to register
326 * @param[in] user_data The user data to be passed to the callback function
327 * @return 0 on success, otherwise a negative error value.
328 * @retval #RADIO_ERROR_NONE Successful
329 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
330 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
331 * @post radio_scan_completed_cb() will be invoked
332 * @see radio_unset_scan_completed_cb()
333 * @see radio_scan_completed_cb()
335 int radio_set_scan_completed_cb(radio_h radio, radio_scan_completed_cb callback, void *user_data);
338 * @brief Unregisters the callback function.
339 * @param[in] radio The handle to radio
340 * @return 0 on success, 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 * @see radio_set_scan_completed_cb()
346 int radio_unset_scan_completed_cb(radio_h radio);
349 * @brief Registers a callback function to be invoked when the radio is interrupted.
350 * @param[in] radio The handle to radio
351 * @param[in] callback The callback function to register
352 * @param[in] user_data The user data to be passed to the callback function
353 * @return 0 on success, otherwise a negative error value.
354 * @retval #RADIO_ERROR_NONE Successful
355 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
356 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
357 * @post radio_interrupted_cb() will be invoked
358 * @see radio_unset_interrupted_cb()
359 * @see #radio_interrupted_code_e
360 * @see radio_interrupted_cb()
362 int radio_set_interrupted_cb(radio_h radio, radio_interrupted_cb callback, void *user_data);
365 * @brief Unregisters the callback function.
366 * @param[in] radio The handle to radio
367 * @return 0 on success, otherwise a negative error value.
368 * @retval #RADIO_ERROR_NONE Successful
369 * @retval #RADIO_ERROR_INVALID_PARAMETER Invalid parameter
370 * @retval #RADIO_ERROR_INVALID_OPERATION Invalid operation
371 * @see radio_set_interrupted_cb()
373 int radio_unset_interrupted_cb(radio_h radio);
383 #endif /* __TIZEN_MEDIA_RADIO_H__ */