/* 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_ssum.h 
 *  $RCSfile: $
 *  $Revision: #3 $
 *  $Date: 2015/08/03 $
 *  $Author: defu.zhen $
 *  
 *  @par Description:
 *         This file contains all c_ssum function prototypes.
 */
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
/*! @defgroup groupMW_SSU_MNGR SSU Manager
 *  @ingroup groupMW
 *  @brief Provides a unified interface for SSU management
 *  %This module allows an application to search for software update in the bitstream.
 *  @see groupMW_TBL_MNGR_DSMCC_ENG, groupMW_TBL_MNGR_DSMCC_DB, groupMW_TBL_MNGR_DSMCC_OC
 *  @{ 
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_SSUM_H_
#define _C_SSUM_H_

/*--------------------------------------------------------------------------
                    include files
--------------------------------------------------------------------------*/
#include "u_ssum.h"


/*--------------------------------------------------------------------------
                    functions declarations
 -------------------------------------------------------------------------*/
/*------------------------------------------------------------------*/
/*! @brief  Open a SSU Manager to detect if there is
 *          - SSU(System Software Update) or
 *          - OAD(Over Air Download)
 *          being trasmitted in the transport stream by checking NIT Actual.
 *  @param  [in]  s_tuner_name  - Tuner name of the tuner receiving the RF signal.
 *  @param  [in]  ui4_oui       - OUI of the manufacturer's software to detect.
 *  @param  [in]  pv_tag        - Memory pointer of the private tag to be used in
 *                                the notification function.
 *  @param  [in]  pf_nfy        - Notification function to be used.
 *  @param  [out] ph_download   - Handle to the SSU Manager being opened.
 *  @note
 *  @see    c_ssum_open_by_type_nid, c_ssum_open_by_setting, c_cm_close
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - Invalid argument, s_tuner_name is NULL.
 *  @retval SSUMR_CORE          - Memory allocation failed.
 *  @retval SSUMR_HANDLE_FAIL   - Handle allocation failed.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_open(CHAR           *s_tuner_name,
                         UINT32         ui4_oui,
                         VOID           *pv_tag,
                         x_ssum_nfy_fct pf_nfy,
                         HANDLE_T       *ph_download);

/*------------------------------------------------------------------*/
/*! @brief  Open a SSU Manager to detect if there is
 *          - SSU(System Software Update) or
 *          - OAD(Over Air Download)
 *          being trasmitted in the transport stream by checking NIT 
 *          with the specified NID(Network ID).
 *  @param  [in]  s_tuner_name        - Tuner name of the tuner receiving the RF signal. 
 *  @param  [in]  pt_ssu_open_setting - Memory pointer to the open setting structure, 
 *                                      which contains OUI and NID.
 *  @param  [in]  pv_tag              - Memory pointer of the private tag to be used in
 *                                      the notification function.
 *  @param  [in]  pf_nfy              - Notification function to be used.
 *  @param  [out] ph_download         - Handle to the SSU Manager being opened.
 *  @note
 *  @see    c_ssum_open, c_ssum_open_by_setting, c_cm_close
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - Invalid argument, s_tuner_name is NULL.
 *  @retval SSUMR_CORE          - Memory allocation failed.
 *  @retval SSUMR_HANDLE_FAIL   - Handle allocation failed.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_open_by_type_nid(CHAR                *s_tuner_name,
                                     SSU_OPEN_SETTING_T  *pt_ssu_open_setting,
                                     VOID                *pv_tag,
                                     x_ssum_nfy_fct      pf_nfy,
                                     HANDLE_T            *ph_download);

/*------------------------------------------------------------------*/
/*! @brief  Open a SSU Manager to detect if there is
 *          - SSU(System Software Update) or
 *          - OAD(Over Air Download)
 *          being trasmitted in the transport stream by checking NIT 
 *          with the specified settings.
 *  @param  [in]  s_tuner_name        - Tuner name of the tuner receiving the RF signal. 
 *  @param  [in]  pt_ssu_open_setting - Memory pointer to the open setting structure, 
 *  @param  [in]  pv_tag              - Memory pointer of the private tag to be used in
 *                                      the notification function.
 *  @param  [in]  pf_nfy              - Notification function to be used.
 *  @param  [out] ph_download         - Handle to the SSU Manager being opened.
 *  @note
 *  @see    c_ssum_open, c_ssum_open_by_type_nid, c_cm_close
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - Invalid argument, s_tuner_name is NULL.
 *  @retval SSUMR_CORE          - Memory allocation failed.
 *  @retval SSUMR_HANDLE_FAIL   - Handle allocation failed.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_open_by_setting(CHAR                 *s_tuner_name,
                                    SSU_OPEN_SETTING_T   *pt_ssu_open_setting,
                                    VOID                 *pv_tag,
                                    x_ssum_nfy_fct       pf_nfy,
                                    HANDLE_T             *ph_download);

/*------------------------------------------------------------------*/
/*! @brief  c_ssum_cancel_download(HANDLE_T h_download).
 *  @param  [in] h_download     - Handle of the SSU Manager to be closed.
 *  @note
 *  @see    c_ssum_open, c_ssum_open_by_type_nid
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - ph_download handle is invalid.
 *  @retval SSUMR_CORE          - Internal error.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/

extern INT32 c_ssum_cancel_download(HANDLE_T h_download);


/*! @brief  Close a SSU Manager specified by h_download, and free related resources.
 *  @param  [in] h_download     - Handle of the SSU Manager to be closed.
 *  @note
 *  @see    c_ssum_open, c_ssum_open_by_type_nid
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - ph_download handle is invalid.
 *  @retval SSUMR_CORE          - Internal error.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_close(HANDLE_T  h_download);

/*------------------------------------------------------------------*/
/*! @brief  Get information from SSU Manager
 *  @param  [in]      h_download      - Handle of the SSU Manager to get info from.
 *  @param  [in]      e_ssu_get_type  - Get type.
 *  @param  [in]      pv_get_info     - Memory pointer to addtional information to be
 *                                      used for the get type.
 *  @param  [out]     pv_get_data     - Memory pointer to contain the get data.
 *  @param  [in,out]  pz_get_data_len - [in]  Contains the max size of pv_get_data.
 *                                    - [out] Contains the size of the returned get data.
 *  @note
 *  @see    c_ssum_set
 *  @return Return the error code
 *  @retval SSUMR_OK      - The routine was successful.
 *  @retval SSUMR_INV_ARG - One of the arguments is invalid.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_get(HANDLE_T         h_download,
                        SSU_GET_TYPE_T   e_ssu_get_type,
                        VOID*            pv_get_info,
                        VOID*            pv_get_data,
                        SIZE_T*          pz_get_data_len);

/*------------------------------------------------------------------*/
/*! @brief  Set information to SSU Manager
 *  @param  [in]  h_download      - Handle of the SSU Manager to get info from.
 *  @param  [in]  e_ssu_set_type  - Set type.
 *  @param  [in]  pv_set_info     - Memory pointer to addtional information to be
 *                                  used for the set type.
 *  @param  [in]  pv_set_data     - Memory pointer to contain the set data.
 *  @param  [in]  pz_set_data_len - Contains the size of the set data.
 *  @note
 *  @see    c_ssum_get
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - One of the arguments is invalid.
 *  @retval SSUMR_CORE          - Internal error.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_set(HANDLE_T         h_download,
                        SSU_SET_TYPE_T   e_ssu_set_type,
                        VOID*            pv_set_info,
                        VOID*            pv_set_data,
                        SIZE_T*          pz_set_data_len);

/*------------------------------------------------------------------*/
/*! @brief  Download file by specifying file ID
 *  @param  [in] h_download - Handle of the SSU Manager to download from
 *  @param  [in] pt_setting - Contains download information, including 
 *                            file ID, buffer length, buffer pointer, and file offset
 *  @param  [in] pv_tag     - Private tag to be used in the download
 *                            progress notification function
 *  @param  [in] pf_nfy     - Download progress notification function
 *  @note
 *  @see    c_ssum_download_by_name
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - One of the arguments is invalid.
 *  @retval SSUMR_CORE          - Internal error.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_download_by_id(HANDLE_T                 h_download,
                                   SSU_DOWNLOAD_SETTING_T   *pt_setting,
                                   VOID                     *pv_tag,
                                   x_ssum_download_nfy_fct  pf_nfy);

/*------------------------------------------------------------------*/
/*! @brief  Download file by specifying file ID
 *  @param  [in] h_download - Handle of the SSU Manager to download from
 *  @param  [in] pt_setting - Contains download information, including 
 *                            file ID, buffer length, buffer pointer, and file offset
 *  @param  [in] pv_tag     - Private tag to be used in the download
 *                            progress notification function
 *  @param  [in] pf_nfy     - Download progress notification function
 *  @note
 *  @see    c_ssum_download_by_name
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - One of the arguments is invalid.
 *  @retval SSUMR_CORE          - Internal error.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/

INT32 c_ssum_download_by_id_mtal(HANDLE_T                h_download,
                                 SSU_DOWNLOAD_SETTING_T  *pt_setting,
                                 VOID                    *pv_tag,
                                 x_dsmcc_download_progress_fct pf_nfy);

INT32 c_ssum_reback_buff(DSMCC_DLD_CTRL_BUF_T *pt_buf);
/*! @brief  Download file by specifying file ID with two buffers
 *  @param  [in] h_download - Handle of the SSU Manager to download from
 *  @param  [in] pt_setting - Contains download information, including 
 *                            file ID, buffer length, buffer pointer, and file offset
 *  @param  [in] pv_tag     - Private tag to be used in the download
 *                            progress notification function
 *  @param  [in] pf_nfy     - Download progress notification function
 *  @note
 *  @see    c_ssum_download_by_name
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - One of the arguments is invalid.
 *  @retval SSUMR_CORE          - Internal error.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_download_by_id_ex(HANDLE_T                    h_download,
                                      SSU_DOWNLOAD_SETTING_EX_T   *pt_setting,
                                      VOID                        *pv_tag,
                                      x_ssum_download_nfy_fct     pf_nfy);

/*------------------------------------------------------------------*/
/*! @brief  Download file by specifying file name
 *  @param  [in] h_download - Handle of the SSU Manager to download from
 *  @param  [in] pt_setting - Contains download information, including
 *                            file name, buffer length, buffer pointer, and file offset
 *  @param  [in] pv_tag     - Private tag to be used in the download
 *                            progress notification function
 *  @param  [in] pf_nfy     - Download progress notification function
 *  @note
 *  @see    c_ssum_download_by_id
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - One of the arguments is invalid.
 *  @retval SSUMR_CORE          - Internal error.
 *  @retval SSUMR_SEND_MSG_FAIL - Internal message sent failed.
 */
/*------------------------------------------------------------------*/
extern INT32 c_ssum_download_by_name(HANDLE_T      h_download,
                                     SSU_DOWNLOAD_SETTING_T     *pt_setting,
                                     VOID                       *pv_tag,
                                     x_ssum_download_nfy_fct    pf_nfy);

/*------------------------------------------------------------------*/
/*! @brief  Get current DDB number
 *  @param  [in] h_download - Handle of the SSU Manager to download from
 *  @param  [in] UINT32     - Current DDB number
 *  @note
 *  @see    c_ssum_get_current_ddb_number
 *  @return Return the error code
 *  @retval SSUMR_OK            - The routine was successful.
 *  @retval SSUMR_INV_ARG       - One of the arguments is invalid.
 *  @retval SSUMR_CORE          - Internal error.
 */
/*------------------------------------------------------------------*/
/*extern INT32 c_ssum_get_current_ddb_number(HANDLE_T    h_download,
                                           UINT32*     ui4_ddb_number);*/
extern  INT32 c_ssum_get_current_ddb_number(HANDLE_T    h_download,
                                        UINT32      ui4_file_id,
                                        UINT32*     ui4_ddb_number, 
                                        UINT32*     ui4_dii_module_number,
                                        UINT32*     ui4_block_size);

#endif

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

