/*
 * HAL (Hardware Abstract Layer) Common API
 *
 * Copyright (c) 2021 Samsung Electronics Co., Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the License);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef __HAL_RADIO__
#define __HAL_RADIO__

#ifdef __cplusplus
extern "C" {
#endif

#include "hal-radio-interface.h"

hal_radio_error_t hal_radio_get_backend(void **hal_radio_handle);

hal_radio_error_t hal_radio_put_backend(void *hal_radio_handle);

/**
 * @brief Initializes new handle of radio HAL.
 * @since_tizen 6.5
 * @param[out] hal_radio_handle A newly returned the radio HAL handle
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_OUT_OF_MEMORY Out of memory
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 * @see radio_deinit()
 */
hal_radio_error_t hal_radio_init(void *hal_radio_handle);

/**
 * @brief Deinitializes handle of radio HAL.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @see radio_init()
 */
hal_radio_error_t hal_radio_deinit(void *hal_radio_handle);

/**
 * @brief Prepare the device of radio.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 * @see radio_unprepare()
 */
hal_radio_error_t hal_radio_prepare(void *hal_radio_handle);

/**
 * @brief Unprepare the device of radio.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 * @see radio_prepare()
 */
hal_radio_error_t hal_radio_unprepare(void *hal_radio_handle);

/**
 * @brief Opens the device of radio.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_DEVICE_NOT_FOUND Failed to find radio device
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 * @retval #HAL_HAL_RADIO_ERROR_PERMISSION_DENIED The access to the resources can not be granted.
 * @retval #HAL_RADIO_ERROR_DEVICE_NOT_PREPARED Not prepared the radio device
 * @see radio_close()
 */
hal_radio_error_t hal_radio_open(void *hal_radio_handle);

/**
 * @brief Closes the device of radio.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_DEVICE_NOT_OPENED The radio device is not opened.
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 * @see radio_open()
 */
hal_radio_error_t hal_radio_close(void *hal_radio_handle);

/**
 * @brief Starts the device of radio.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_DEVICE_NOT_OPENED The radio device is not opened.
 * @see radio_stop()
 */
hal_radio_error_t hal_radio_start(void *hal_radio_handle);

/**
 * @brief Stops the device of radio.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_DEVICE_NOT_OPENED The radio device is not opened.
 * @see radio_start()
 */
hal_radio_error_t hal_radio_stop(void *hal_radio_handle);

/**
 * @brief Seeks (up or down) the effective frequency of the radio.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @param[in] direction The seek direction type (up or down)
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_DEVICE_NOT_OPENED The radio device is not opened
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 */
hal_radio_error_t hal_radio_seek(void *hal_radio_handle, hal_radio_seek_direction_type_t direction);

/**
 * @brief Gets the radio frequency.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @param[out] frequency The current frequency (khz)
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 */
hal_radio_error_t hal_radio_get_frequency(void *hal_radio_handle, uint32_t *frequency);

/**
 * @brief Sets the radio frequency.
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @param[in] frequency The frequency to set (khz)
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 */
hal_radio_error_t hal_radio_set_frequency(void *hal_radio_handle, uint32_t frequency);

/**
 * @brief Gets the current signal strength of the radio
 * @since_tizen 6.5
 * @param[in] hal_radio_handle The radio HAL handle
 * @param[out] strength The current signal strength (dBm)
 * @return @c 0 on success, otherwise a negative error value
 * @retval #HAL_RADIO_ERROR_NONE Successful
 * @retval #HAL_RADIO_ERROR_INVALID_PARAMETER Invalid parameter
 * @retval #HAL_RADIO_ERROR_INVALID_OPERATION Invalid operation
 */
hal_radio_error_t hal_radio_get_signal_strength(void *hal_radio_handle, int32_t *strength);

#ifdef __cplusplus
}
#endif
#endif /* __HAL_RADIO__ */