/* SPDX-License-Identifier: LGPL-2.1-only OR BSD-3-Clause */
/******************************************************************************
 *
 * This file is provided under a dual license.  When you use or
 * distribute this software, you may choose to be licensed under
 * version 2.1 of the GNU Lesser General Public License
 * ("LGPLv2.1 License") or BSD License.
 *
 * LGPLv2.1 License
 *
 * Copyright(C) 2019 MediaTek Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of version 2.1 of the GNU Lesser General Public
 * License as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html for more
 * details.
 *
 * BSD LICENSE
 *
 * Copyright(C) 2019 MediaTek Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *  * Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *****************************************************************************/

 /*----------------------------------------------------------------------------*/
/*! @file c_sb.h 
 *  $RCSfile: $
 *  $Revision: #1 $
 *  $Date: 2015/06/01 $
 *  $Author: cheng.liu $
 *  
 *  @par Description:
 *         This header file contains Svl Builder engine specific definitions,
 *         which are exported for applications.
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_SB_H_
#define _C_SB_H_  /**< svl builder c interface header file */

/*----------------------------------------------------------------------------*/
/*! @defgroup groupMW_SVL_BLDR SVL Builder
 *  @ingroup groupMW
 *  @brief The Svl builder module is the super module of other svl builder engine
 *  %MW Application API would be used by Application, lot of these APIs would
 *   be wrapped from Exported API. Using these APIs, application could create scan engine
 *   or start scan from the exported API of svl builder.
 *   
 *  @see groupMW_SVL_BLDR
 *  @{ 
 */
/*----------------------------------------------------------------------------*/

/*-----------------------------------------------------------------------------
                    include files
 ----------------------------------------------------------------------------*/

#include "u_sb.h"


/*-----------------------------------------------------------------------------
                    macros, defines, typedefs, enums
 ----------------------------------------------------------------------------*/
#define SB_ATSC_GEN_CHANNEL_ID(major, minor, index)    \
    (c_sb_gen_channel_id((UINT32)major, (UINT32)minor, (UINT32)index))

#define SB_ATSC_GEN_ONE_PART_CHANNEL_ID(major, index) \
    (c_sb_gen_one_part_channel_id((UINT32)major,(UINT32)index))

#define SB_ATSC_GEN_NON_PSIP_CHANNEL_ID(major, minor, index) \
    (c_sb_gen_non_psip_channel_id((UINT32)major, (UINT32)minor, (UINT32)index))

#define SB_ATSC_IS_ONE_PART_CHANNEL_ID(channel_id) \
    (c_sb_is_one_part_channel_id((UINT32)channel_id))

#define SB_ATSC_IS_NON_PSIP_CHANNEL_ID(channel_id) \
    (c_sb_is_non_psip_channel_id((UINT32) channel_id))

#define SB_ATSC_GET_MAJOR_CHANNEL_NUM(channel_id) \
    (c_sb_get_major_channel_num((UINT32) channel_id))

#define SB_ATSC_GET_MINOR_CHANNEL_NUM(channel_id) \
    (c_sb_get_minor_channel_num((UINT32) channel_id))

#define SB_ATSC_GET_CHANNEL_INDEX(channel_id)              \
    (c_sb_get_channel_index((UINT32) channel_id))

#define SB_ATSC_MAX_CHANNEL_INDEX     (c_sb_max_channel_index())

#define SB_NTSC_CAB_SCAN_LAST_CHANNEL (c_sb_get_cable_last_channel())

#define SB_CQAM_SCAN_LAST_CHANNEL     (c_sb_get_cable_last_channel())

/*-----------------------------------------------------------------------------
                    functions declaraions
 ----------------------------------------------------------------------------*/

/*------------------------------------------------------------------*/
/*! @brief This API Check the svl builder module is initiated.
 *  @param [in]  void               - N/A.
 *
 *  @return Return the boolean value of initiated is done or not.
 *  @retval TRUE                  - It is initiated.
 *          FALSE                 - Not yet initiated.
 */
/*------------------------------------------------------------------*/

BOOL c_sb_is_inited(VOID);


/*------------------------------------------------------------------*/
/*! @brief This API Create a builder engine.
 *  @param [in]  ps_builder_name    - The engine name defined by each engine which is ususlly located in u_sb_xxx_eng.h .
 *  @param [in]  pv_open_data       - The paramater for creating engine object which is ussully located in u_sb_xxx_eng.h.
 *  @param [in]  pv_nfy_tag         - The paramater bring back by pf_nfy, the engine would not change/use it.
 *  @param [in]  pf_nfy             - The notified function.
 *  @param [out] ph_builder         - The sb engine handle.
 *  @param [out] pe_builder_cond   -  The engine condition.
 *
 *
 *  @note The engine is working on singlton pattern.
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_BLDR_NOT_FOUND      - Fail. The builder engine was not found.
 *          SBR_FILE_NOT_FOUND      - Fail. The ps_file_name was not found.
 *          SBR_INTERNAL_ERROR      - Fail. Internal error happens.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_LIST_NOT_FOUND      - Fail. The named SVL doesn't exist.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 *          SBR_OUT_OF_HANDLES      - Fail. Run out of handles.
 *          SBR_OUT_OF_MEM          - Fail. Run out of memory.
 */
/*------------------------------------------------------------------*/
INT32 c_sb_open_builder(
    const CHAR*         ps_builder_name,
    VOID*               pv_open_data,
    VOID*               pv_nfy_tag,
    x_sb_nfy_fct        pf_nfy,
    HANDLE_T*           ph_builder,
    SB_COND_T*          pe_builder_cond);
    

/*------------------------------------------------------------------*/
/*! @brief This API close a builder engine.
 *  @param [in]  h_builder    - The engine handle closeing.
 *
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *         SBR_INTERNAL_ERROR       - Fail. Internal error happens.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_INV_HANDLE          - Fail. Invalid builder handle.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 */
/*------------------------------------------------------------------*/
INT32 c_sb_close_builder(
    HANDLE_T            h_builder);

/*------------------------------------------------------------------*/
/*! @brief This API start a scan.
 *  @param [in]  ph_builder         - The sb engine handle.
 *  @param [in]  pv_scan_data       - Contains the builder engine specific scan data. It is ussully located in u_sb_xxx_eng.h.
 *  @param [in]  pv_nfy_tag         - Contains the caller private tag. The paramater bring back by pf_nfy, the engine would not change/use it.
 *  @param [in]  pf_nfy             - The notified function. This function used to notify AP the scan progress.
 *  @param [out] pe_builder_cond   -  The engine condition.
 *
 *
 *  @note The engine is working on singlton pattern.
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_INTERNAL_ERROR      - Fail. Internal error happens.
 *          SBR_INV_COND            - Fail. Invalid condition.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_INV_HANDLE          - Fail. Invalid builder handle.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 */
/*------------------------------------------------------------------*/

INT32 c_sb_start_scan(
    HANDLE_T            h_builder,
    VOID*               pv_scan_data,
    VOID*               pv_nfy_tag,
    x_sb_scan_nfy_fct   pf_nfy,
    SB_COND_T*          pe_builder_cond);


/*------------------------------------------------------------------*/
/*! @brief This cancel a scan.
 *  @param [in]  h_builder    - The engine handle scaning.
 *
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_INTERNAL_ERROR      - Fail. Internal error happens.
 *          SBR_INV_COND            - Fail. Invalid condition.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_INV_HANDLE          - Fail. Invalid builder handle.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 */
/*------------------------------------------------------------------*/
INT32 c_sb_cancel_scan(
    HANDLE_T            h_builder);
    
/*------------------------------------------------------------------*/
/*! @brief API to store the SVL and TSL.
 *  @param [in]  h_builder    - The engine handle scaning.
 *  @param [in]  ps_file_name - The file in which the lists are stored.
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_ERR_SAVE_LIST       - Fail. An error happened when saving SVL or TSL.
 *          SBR_INV_COND            - Fail. Invalid condition.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_INV_HANDLE          - Fail. Invalid builder handle.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 */
/*------------------------------------------------------------------*/
INT32 c_sb_save_lists(
    HANDLE_T            h_builder,
    const CHAR*         ps_file_name);

/*------------------------------------------------------------------*/
/*! @brief API to load the SVL and TSL.
 *  @param [in]  h_builder    - The engine handle scaning.
 *  @param [in]  ps_file_name - The file in which the lists are stored.
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_ERR_LOAD_LIST       - Fail. An error happened when loading SVL or TSL. 
 *          SBR_FILE_NOT_FOUND      - Fail. The specified ps_file_name was not found.
 *          SBR_INV_COND            - Fail. Invalid condition.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_INV_HANDLE          - Fail. Invalid builder handle.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 */
/*------------------------------------------------------------------*/
INT32 c_sb_load_lists(
    HANDLE_T            h_builder,
    const CHAR*         ps_file_name);

/*------------------------------------------------------------------*/
/*! @brief API to clean the SVL and TSL from a file.
 *  @param [in]  h_builder    - The engine handle scaning.
 *  @param [in]  ps_file_name - The file in which the lists are stored.
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_ERR_CLEAN_LIST      - Fail. An error happened when cleaning SVL or TSL. 
 *          SBR_FILE_NOT_FOUND      - Fail. The specified ps_file_name was not found.
 *          SBR_INV_COND            - Fail. Invalid condition.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_INV_HANDLE          - Fail. Invalid builder handle.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 */
/*------------------------------------------------------------------*/
INT32 c_sb_clean_lists(
    HANDLE_T            h_builder,
    const CHAR*         ps_file_name);


/*------------------------------------------------------------------*/
/*! @brief API to get requested type data from the builder engine.
 *  @param [in]  h_builder      - The engine handle scaning.
 *  @param [in]  e_key_type     - The requested type to get.
 *  @param [in]  pv_key_info    - The auxiliary info for the requested get type.
 *  @param [in]  pz_key_data_len - Contains length of the buffer to which pv_key_data points.
 *  @param [out] pz_key_data_len - Contains the real length of retrieved key data if the API successfully returns.
 *
 *
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_ERR_CLEAN_LIST      - Fail. An error happened when cleaning SVL or TSL. 
 *          SBR_FILE_NOT_FOUND      - Fail. The specified ps_file_name was not found.
 *          SBR_INV_COND            - Fail. Invalid condition.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_INV_HANDLE          - Fail. Invalid builder handle.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 */
/*------------------------------------------------------------------*/
INT32 c_sb_get(
    HANDLE_T            h_builder,
    SB_KEY_TYPE_T       e_key_type,
    VOID*               pv_key_info,
    SIZE_T*             pz_key_data_len,
    VOID*               pv_key_data);

/*------------------------------------------------------------------*/
/*! @brief API to set requested type data from the builder engine.
 *  @param [in]  h_builder      - The engine handle scaning.
 *  @param [in]  e_key_type     - The requested type to get.
 *  @param [in]  pv_key_info    - The auxiliary info for the requested get type.
 *  @param [in]  z_key_data_len - Contains length of the buffer to which pv_key_data points.
 *  @param [out] pz_key_data_len - Contains the real length of retrieved key data if the API successfully returns.
 *
 *
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_ERR_CLEAN_LIST      - Fail. An error happened when cleaning SVL or TSL. 
 *          SBR_FILE_NOT_FOUND      - Fail. The specified ps_file_name was not found.
 *          SBR_INV_COND            - Fail. Invalid condition.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 *          SBR_INV_HANDLE          - Fail. Invalid builder handle.
 *          SBR_NOT_INIT            - Fail. The SB component is not initialized yet.
 */
/*------------------------------------------------------------------*/

INT32 c_sb_set(
    HANDLE_T            h_builder,
    SB_KEY_TYPE_T       e_key_type,
    VOID*               pv_key_info,
    SIZE_T              z_key_data_len,
    VOID*               pv_key_data);


/*------------------------------------------------------------------*/
/*! @brief API to registe builder engine scan maps.
 *  @param [in]  ps_eng_name      - The sub-engine name.
 *  @param [in]  pv_nfy_fct       - The scan map function.
 *
 *  @return Return the error code.
 *  @retval SBR_OK                  - Routine successful.
 *          SBR_INV_ARG             - Fail. Invalid arguments.
 */
/*------------------------------------------------------------------*/
INT32 c_sb_reg_scan_map(
    const CHAR*         ps_eng_name,
    VOID*               pv_nfy_fct);

/* cliu 20090706, Sync cancel scan function to call API of sub egnine */
/*-----------------------------------------------------------------------------
 *! @brief API to cancel a service/channel scan in a thread context.
 *
 *  @param [in]  h_builder      - The engine handle scaning.
 *
 *  @return Return the error code.
 *  @retval SBR_OK              Success.
 *          SBR_INTERNAL_ERROR  Fail. Internal error happens.
 *          SBR_INV_ARG         Fail. Invalid arguments.
 *          SBR_INV_COND        Fail. Invalid condition.
 *          SBR_INV_HANDLE      Fail. Invalid builder handle.
 *          SBR_NOT_INIT        Fail. The SB component is not initialized yet.
 *
 ----------------------------------------------------------------------------*/
INT32 c_sb_cancel_scan_sync(
    HANDLE_T            h_builder);

/*-----------------------------------------------------------------------------
 *! @brief API to get the current builder condition.
 *
 *  @param [in]  h_builder      - The engine handle scaning.
 *  @param [out] pe_builder_cond  - Contains the current builder condition.
 *
 *  @return Return the error code.
 *  @retval SBR_OK              Success.
 *          SBR_INV_ARG         Fail. Invalid arguments.
 *          SBR_INV_HANDLE      Fail. Invalid builder handle.
 *          SBR_NOT_INIT        Fail. The SB component is not initialized yet.
 *
 ----------------------------------------------------------------------------*/
INT32 c_sb_get_cond(
    HANDLE_T            h_builder,
    SB_COND_T*          pe_builder_cond);

/*-----------------------------------------------------------------------------
*! @brief API to returns the current setting of debug level.
 *
 *  @return Return the error code.
 ----------------------------------------------------------------------------*/     
UINT16 c_sb_get_dbg_level(VOID);

/*-----------------------------------------------------------------------------
 *! @brief API to changes the setting of debug level to new one.
 *
 *
 * @param [in] ui2_level     -The new setting of debug level.  
 *  @return Return executed status.
 *  @retval TRUE            Routine successful.
 *          FALSE           Routine failed.
 ----------------------------------------------------------------------------*/ 
BOOL c_sb_set_dbg_level(
    UINT16              ui2_level);

/*-----------------------------------------------------------------------------
 *! @brief This API is to generate channel id.
 *
 *
 * @param [in] major     -
 * @param [in] minor     -
 * @param [in] index     -
 *  @return the value of generate channel id
 ----------------------------------------------------------------------------*/
UINT32 c_sb_gen_channel_id(
     UINT32                     major,
     UINT32                     minor,
     UINT32                     index);

/*-----------------------------------------------------------------------------
 *! @brief This API is to generate channel id.
 *
 *
 * @param [in] major     -
 * @param [in] index     -
 *  @return the value of generate channel id
 ----------------------------------------------------------------------------*/
UINT32 c_sb_gen_one_part_channel_id(
      UINT32                              major,
      UINT32                              index);

/*-----------------------------------------------------------------------------
 *! @brief This API is to generate non psip channel id.
 *
 *
 * @param [in] major     -
 * @param [in] index     -
 *  @return the value of generate channel id
 ----------------------------------------------------------------------------*/
UINT32 c_sb_gen_non_psip_channel_id(
      UINT32                              major,
      UINT32                              minor,
      UINT32                              index);

/*-----------------------------------------------------------------------------
 *! @brief This API is to check channel id is one part or not.
 *
 *
 * @param [in] channel_id     -
 *  @return
 * @retval  TRUE - is one part channel id
 ----------------------------------------------------------------------------*/
BOOL c_sb_is_one_part_channel_id(UINT32 channel_id);

/*-----------------------------------------------------------------------------
 *! @brief This API is to check channel id is non psip or not.
 *
 *
 * @param [in] channel_id     -
 *  @return
 * @retval  TRUE - is non psip channel id
 ----------------------------------------------------------------------------*/
BOOL c_sb_is_non_psip_channel_id(UINT32 channel_id);

/*-----------------------------------------------------------------------------
 *! @brief This API is to get major channel number from channel id
 *
 *
 * @param [in] channel_id     -
 *  @return
 * @retval  major channel num
 ----------------------------------------------------------------------------*/
UINT16 c_sb_get_major_channel_num(UINT32 channel_id);

/*-----------------------------------------------------------------------------
 *! @brief This API is to get minor channel number from channel id
 *
 *
 * @param [in] channel_id     -
 *  @return
 * @retval  minor channel num
 ----------------------------------------------------------------------------*/
UINT16 c_sb_get_minor_channel_num(UINT32 channel_id);

/*-----------------------------------------------------------------------------
 *! @brief This API is to get index number from channel id
 *
 *
 * @param [in] channel_id     -
 *  @return
 * @retval  index num
 ----------------------------------------------------------------------------*/
UINT8 c_sb_get_channel_index(UINT32 channel_id);

/*-----------------------------------------------------------------------------
 * Name: c_sb_max_channel_index
 *
 * Description: This API is get max channel index.
 *
 * Inputs: UINT32 channel_id
 *
 * Outputs: -
 *
 * Returns:
 *             max channel index
 ----------------------------------------------------------------------------*/
UINT32 c_sb_max_channel_index(VOID);

/*-----------------------------------------------------------------------------
 * Name: c_sb_get_cable_last_channel
 *
 * Description: This API is return the cable last channel value from cfg_parser
 *              by macro:MW_SB_CABLE_LAST_CHANNEL.
 *
 * Inputs:
 *
 * Outputs: -
 *
 * Returns:
 *         the value of macro MW_SB_CABLE_LAST_CHANNEL
 ----------------------------------------------------------------------------*/
 UINT16 c_sb_get_cable_last_channel(VOID);

/*----------------------------------------------------------------------------*/
/*! @} */                                           /* end of groupMW_SVL_BLDR*/
/*----------------------------------------------------------------------------*/

#endif /* _C_SB_H_ */

