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 Starts scanning radio signals, asynchronously
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()
266 int radio_scan_start(radio_h radio, radio_scan_updated_cb callback, void *user_data);
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()
283 int radio_scan_stop(radio_h radio, radio_scan_stopped_cb callback, void *user_data);
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()
296 int radio_set_mute(radio_h radio, bool muted);
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()
309 int radio_is_muted(radio_h radio, bool *muted);
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()
324 int radio_set_scan_completed_cb(radio_h radio, radio_scan_completed_cb callback, void *user_data);
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()
335 int radio_unset_scan_completed_cb(radio_h radio);
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()
351 int radio_set_interrupted_cb(radio_h radio, radio_interrupted_cb callback, void *user_data);
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()
362 int radio_unset_interrupted_cb(radio_h radio);
372 #endif /* __TIZEN_MEDIA_RADIO_H__ */