/* 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_cm.h 
 *  $RCSfile: $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This header file contains definitions of the Connection Manager
 *         application APIs (c_*).
 */
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
/*! @defgroup groupMW_CONN_MNGR Connection Manager
 *  @ingroup groupMW
 *  @brief Provides a unified interface for connection management
 *  %This module allows an application to create and control any type of
 *  connection regardless of the data source type.
 *   - including these sub modules:
 *  @see groupMW
 *  @{ 
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_CM_H_
#define _C_CM_H_


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

#include "u_cm.h"
#include "u_common.h"
#include "u_handle.h"


/*-----------------------------------------------------------------------------
                    functions declarations
 ----------------------------------------------------------------------------*/

/*------------------------------------------------------------------*/
/*! @brief Destroys a pipeline, previously created with c_cm_open_pipe
 *  @param [in]  h_pipe         -   Contains the handle identifying the pipeline
 *  @param [out] pe_cond        -   Contains the condition of the pipeline closure. In case the routine 
 *                                  was not successful, the value of this argument is undetermined. 
 *                                  This argument may be set to NULL.
 *  @note	This API is only called from a thread context
 *  @return Return the error code
 *  @retval CMR_OK     			-	The routine was successful.
 *  @retval CMR_INV_HANDLE     	-	The argument h_pipe does contain an invalid or unused handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cm_close_pipe (HANDLE_T    h_pipe,
                              CM_COND_T*  pe_cond);

/*------------------------------------------------------------------*/
/*! @brief Connects a pipeline to some data source
 *  @param [in]  h_obj          -   Contains a handle to a pipeline, which was created using the 
 *                                  API c_cm_open_pipe, or a handle to an existing connection.
 *  @param [in]  pt_connect_cmd -   Contains the command array. This argument may also be set to NULL.
 *  @param [in]  pv_nfy_tag     -   Contains a tag value which is returned with any notification
 *  @param [in]  pv_tag         -   References the notify function which the Connection Manager 
 *                                  executes for connection related events.
 *  @param [out] ph_conn        -   Contains the handle identifying the connection if the routine was successful. 
 *  @param [out] pe_cond        -   Contains the condition of the newly allocated connection. 
 *  @return Return the error code
 *  @retval CMR_OK              -   The routine was successful.
 *  @retval CMR_INV_ARG         -   The arguments pf_nfy or ph_connection contain a NULL pointer, 
 *                                  or the command array contains invalid commands.
 *  @retval CMR_INV_HANDLE      -   The argument h_pipe does contain an invalid or unused handle.
 *  @retval CMR_OUT_OF_HANDLES  -   No handle was available.
 *  @retval CMR_INV_COMMAND     -   The command set is invalid: invalid source type, etc.
 *  @retval CMR_NO_HANDLER      -   No connection handler has been found.
 *  @retval CMR_FAIL            -   The routine was unsuccessful for some other reason.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cm_connect (HANDLE_T             h_obj,
                           const CM_COMMAND_T*  pt_connect_cmd,
                           VOID*                pv_nfy_tag,
                           x_cm_nfy_fct         pf_nfy,
                           HANDLE_T*            ph_conn,
                           CM_COND_T*           pe_cond);

/*------------------------------------------------------------------*/
/*! @brief Destroys a connection. 
 *  @param [in]  h_conn     -   Contains the connection handle which was created by the API c_cm_connect.
 *  @param [out] pe_cond    -   Contains the condition of the connection (either CM_COND_DISCONNETING 
 *                              or CM_COND_DISCONNETED). 
 *  @return Return the error code
 *  @retval CMR_OK              -   The routine was successful. 
 *  @retval CMR_INV_HANDLE      -   The argument h_pipe does contain an invalid or unused handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cm_disconnect (HANDLE_T    h_conn,
                              CM_COND_T*  pe_cond);

/*------------------------------------------------------------------*/
/*! @brief Gets some data/information about a connection
 *  @param [in]  h_conn         -   Contains the connection handle which was created by the API c_cm_connect.
 *  @param [in]  e_ctrl         -   Contains the control type .
 *  @param [in]  pv_get_data    -   Contains additional data whose interpretation depends on the argument e_ctrl.
 *  @param [out] pv_get_data    -   If the value of argument e_ctrl indicates a synchronous operation 
 *                                  the data pv_get_data points to has been modified accordingly.
 *  @return Return the error code
 *  @retval CMR_OK              -   The routine was successful.
 *  @retval CMR_INV_ARG         -   The arguments pf_nfy or ph_connection contain a NULL pointer, 
 *                                  or the command array contains invalid commands.
 *  @retval CMR_INV_HANDLE      -   The argument h_pipe does contain an invalid or unused handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cm_get (HANDLE_T        h_conn,
                       CM_CTRL_TYPE_T  e_ctrl,
                       VOID*           pv_get_data);

/*------------------------------------------------------------------*/
/*! @brief Sets some attributes of a connection.
 *  @param [in]  h_conn         -   Contains the connection handle which was created by the API c_cm_connect.
 *  @param [in]  e_ctrl         -   Contains the control type.
 *  @param [in]  pv_set_data    -   Contains additional data whose interpretation depends on the argument e_ctrl.
 *  @param [out] pv_set_data    -   The data pv_set_data points to may have been modified (depending 
 *                                  on the value of e_ctrl).
 *  @return Return the error code
 *  @retval CMR_OK              -   The routine was successful.
 *  @retval CMR_INV_ARG         -   The arguments pf_nfy or ph_connection contain a NULL pointer, 
 *                                  or the command array contains invalid commands.
 *  @retval CMR_INV_HANDLE      -   The argument h_pipe does contain an invalid or unused handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cm_set (HANDLE_T        h_conn,
                       CM_CTRL_TYPE_T  e_ctrl,
                       VOID*           pv_set_data);

/*------------------------------------------------------------------*/
/*! @brief Get the condition of specified connection.
 *  @param [in]  h_conn     -   Contains the connection handle which was created by the API c_cm_connect.
 *  @param [out] pe_cond    -   Contains the connection condition state.
 *  @return Return the error code
 *  @retval CMR_OK          -   The routine was successful.
 *  @retval CMR_INV_ARG     -   The arguments pf_nfy or ph_connection contain a NULL pointer, 
 *                              or the command array contains invalid commands.
 *  @retval CMR_INV_HANDLE  -   The argument h_pipe does contain an invalid or unused handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cm_get_cond (HANDLE_T    h_conn,
                            CM_COND_T*  pe_cond);

/*------------------------------------------------------------------*/
/*! @brief Creates a pipeline, which can be used to create connections.
 *  @param [in]  pt_pipe_cmd    -   Contains the command array. 
 *  @param [in]  ui1_priority   -   This argument contains the pipelines priority. Note that a value
 *                                  of 0 indicates highest and 28 - 1 lowest priority.
 *  @param [in]  ui4_flags      -   Contains the pipeline flags. Unused bits must be set to '0' to 
 *                                  ensure backward compatibility in the future.
 *  @param [in]  pv_nfy_tag     -   Contains a tag value which is returned with any notification. 
 *  @param [in]  pf_nfy         -   References the notify function which the Connection Manager 
 *                                  executes for pipeline related events.
 *  @param [out] ph_pipe        -   Contains the handle identifying the pipeline.
 *  @param [out] pe_cond        -   Contains the condition of the newly created pipeline.
 *  @return Return the error code
 *  @retval CMR_OK              -   The routine was successful.
 *  @retval CMR_INV_ARG         -   The arguments pf_nfy or ph_connection contain a NULL pointer, 
 *                                  or the command array contains invalid commands.
 *  @retval CMR_OUT_OF_HANDLES  -   No handle was available.
 *  @retval CMR_NOT_INIT        -   The Connection Manager is not initialized yet.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cm_open_pipe (const CM_COMMAND_T*  pt_pipe_cmd,
                             UINT8                ui1_priority,
                             UINT32               ui4_flags,
                             VOID*                pv_nfy_tag,
                             x_cm_nfy_fct         pf_nfy,
                             HANDLE_T*            ph_pipe,
                             CM_COND_T*           pe_cond);

/*------------------------------------------------------------------*/
/*! @brief Store input main, broadcast source and channel id to MW EEPROM part when one of them changed.
 *              if not any change, the write operation will be ignore.
 *  @param [in]  b_last_dtv_src    -   Indicate the last src is dtv or not. 
 *  @param [in]  ui1_last_svl_lst   -   Contains last svl list id.
 *  @param [in]  ui4_last_channel_id      -   Contains the last channel id user selected.
 *  @return Return the error code
 *  @retval CMR_OK              -   The routine was successful.
 *  @retval CMR_FAIL         -   The operation failed for eeprom
 */
/*------------------------------------------------------------------*/
extern INT32 c_cm_store_pre_conn_info(BOOL b_last_dtv_src, 
                                    UINT8 ui1_last_svl_lst, 
                                    UINT32 ui4_last_channel_id);
                                            

#endif /* _C_CM_H_ */


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

