include/hal-radio.h

   1 /*
   2  * HAL (Hardware Abstract Layer) Common API
   3  *
   4  * Copyright (c) 2021 Samsung Electronics Co., Ltd.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the License);
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 #ifndef __HAL_RADIO__
  20 #define __HAL_RADIO__
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 #include "hal-radio-interface.h"
  27
  28 hal_radio_error_t hal_radio_get_backend(void **hal_radio_handle);
  29
  30 hal_radio_error_t hal_radio_put_backend(void *hal_radio_handle);
  31
  32 /**
  33  * @brief Initializes new handle of radio HAL.
  34  * @since_tizen 6.5
  35  * @param[out] hal_radio_handle A newly returned the radio HAL handle
  36  * @return @c 0 on success, otherwise a negative error value
  37  * @retval #HAL_RADIO_ERROR_NONE Successful
  38  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
  39  * @retval #HAL_RADIO_ERROR_OUT_OF_MEMORY Out of memory
  40  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
  41  * @see radio_deinit()
  42  */
  43 hal_radio_error_t hal_radio_init(void *hal_radio_handle);
  44
  45 /**
  46  * @brief Deinitializes handle of radio HAL.
  47  * @since_tizen 6.5
  48  * @param[in] hal_radio_handle The radio HAL handle
  49  * @return @c 0 on success, otherwise a negative error value
  50  * @retval #HAL_RADIO_ERROR_NONE Successful
  51  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
  52  * @see radio_init()
  53  */
  54 hal_radio_error_t hal_radio_deinit(void *hal_radio_handle);
  55
  56 /**
  57  * @brief Prepare the device of radio.
  58  * @since_tizen 6.5
  59  * @param[in] hal_radio_handle The radio HAL handle
  60  * @return @c 0 on success, otherwise a negative error value
  61  * @retval #HAL_RADIO_ERROR_NONE Successful
  62  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
  63  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
  64  * @see radio_unprepare()
  65  */
  66 hal_radio_error_t hal_radio_prepare(void *hal_radio_handle);
  67
  68 /**
  69  * @brief Unprepare the device of radio.
  70  * @since_tizen 6.5
  71  * @param[in] hal_radio_handle The radio HAL handle
  72  * @return @c 0 on success, otherwise a negative error value
  73  * @retval #HAL_RADIO_ERROR_NONE Successful
  74  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
  75  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
  76  * @see radio_prepare()
  77  */
  78 hal_radio_error_t hal_radio_unprepare(void *hal_radio_handle);
  79
  80 /**
  81  * @brief Opens the device of radio.
  82  * @since_tizen 6.5
  83  * @param[in] hal_radio_handle The radio HAL handle
  84  * @return @c 0 on success, otherwise a negative error value
  85  * @retval #HAL_RADIO_ERROR_NONE Successful
  86  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
  87  * @retval #HAL_RADIO_ERROR_DEVICE_NOT_FOUND Failed to find radio device
  88  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
  89  * @retval #HAL_HAL_RADIO_ERROR_PERMISSION_DENIED The access to the resources can not be granted.
  90  * @retval #HAL_RADIO_ERROR_DEVICE_NOT_PREPARED Not prepared the radio device
  91  * @see radio_close()
  92  */
  93 hal_radio_error_t hal_radio_open(void *hal_radio_handle);
  94
  95 /**
  96  * @brief Closes the device of radio.
  97  * @since_tizen 6.5
  98  * @param[in] hal_radio_handle The radio HAL handle
  99  * @return @c 0 on success, otherwise a negative error value
 100  * @retval #HAL_RADIO_ERROR_NONE Successful
 101  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 102  * @retval #HAL_RADIO_ERROR_DEVICE_NOT_OPENED The radio device is not opened.
 103  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 104  * @see radio_open()
 105  */
 106 hal_radio_error_t hal_radio_close(void *hal_radio_handle);
 107
 108 /**
 109  * @brief Starts the device of radio.
 110  * @since_tizen 6.5
 111  * @param[in] hal_radio_handle The radio HAL handle
 112  * @return @c 0 on success, otherwise a negative error value
 113  * @retval #HAL_RADIO_ERROR_NONE Successful
 114  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 115  * @retval #HAL_RADIO_ERROR_DEVICE_NOT_OPENED The radio device is not opened.
 116  * @see radio_stop()
 117  */
 118 hal_radio_error_t hal_radio_start(void *hal_radio_handle);
 119
 120 /**
 121  * @brief Stops the device of radio.
 122  * @since_tizen 6.5
 123  * @param[in] hal_radio_handle The radio HAL handle
 124  * @return @c 0 on success, otherwise a negative error value
 125  * @retval #HAL_RADIO_ERROR_NONE Successful
 126  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 127  * @retval #HAL_RADIO_ERROR_DEVICE_NOT_OPENED The radio device is not opened.
 128  * @see radio_start()
 129  */
 130 hal_radio_error_t hal_radio_stop(void *hal_radio_handle);
 131
 132 /**
 133  * @brief Seeks (up or down) the effective frequency of the radio.
 134  * @since_tizen 6.5
 135  * @param[in] hal_radio_handle The radio HAL handle
 136  * @param[in] direction The seek direction type (up or down)
 137  * @return @c 0 on success, otherwise a negative error value
 138  * @retval #HAL_RADIO_ERROR_NONE Successful
 139  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 140  * @retval #HAL_RADIO_ERROR_DEVICE_NOT_OPENED The radio device is not opened
 141  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 142  */
 143 hal_radio_error_t hal_radio_seek(void *hal_radio_handle, hal_radio_seek_direction_type_t direction);
 144
 145 /**
 146  * @brief Gets the radio frequency.
 147  * @since_tizen 6.5
 148  * @param[in] hal_radio_handle The radio HAL handle
 149  * @param[out] frequency The current frequency (khz)
 150  * @return @c 0 on success, otherwise a negative error value
 151  * @retval #HAL_RADIO_ERROR_NONE Successful
 152  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 153  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 154  */
 155 hal_radio_error_t hal_radio_get_frequency(void *hal_radio_handle, uint32_t *frequency);
 156
 157 /**
 158  * @brief Sets the radio frequency.
 159  * @since_tizen 6.5
 160  * @param[in] hal_radio_handle The radio HAL handle
 161  * @param[in] frequency The frequency to set (khz)
 162  * @return @c 0 on success, otherwise a negative error value
 163  * @retval #HAL_RADIO_ERROR_NONE Successful
 164  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 165  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 166  */
 167 hal_radio_error_t hal_radio_set_frequency(void *hal_radio_handle, uint32_t frequency);
 168
 169 /**
 170  * @brief Gets the current signal strength of the radio
 171  * @since_tizen 6.5
 172  * @param[in] hal_radio_handle The radio HAL handle
 173  * @param[out] strength The current signal strength (dBm)
 174  * @return @c 0 on success, otherwise a negative error value
 175  * @retval #HAL_RADIO_ERROR_NONE Successful
 176  * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 177  * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 178  */
 179 hal_radio_error_t hal_radio_get_signal_strength(void *hal_radio_handle, int32_t *strength);
 180
 181 #ifdef __cplusplus
 182 }
 183 #endif
 184 #endif /* __HAL_RADIO__ */