/* 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_dsm.h 
 *  $RCSfile: $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *    This header file contains Device Status Manager (DSM) API definitions,
 *    which are exported to other Middleware components and applications.
 *         
 */
/*----------------------------------------------------------------------------*/

/*----------------------------------------------------------------------------*/
 /*! @addtogroup groupMW_DSM
  *  @{ 
  */
/*----------------------------------------------------------------------------*/

#ifndef _C_DSM_H_
#define _c_DSM_H_

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

#include "u_dsm.h"

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

/*------------------------------------------------------------------*/
/*!@brief   This function create a handle to  a device interface group. 
 *  @param [in]  t_dev_group  The interface specified is one of the following
 *                                       interface:
 *                                       DEV_1394, DEV_TUNER, DEV_AVC.
 *  @param [in]  pv_tag          Private tag that will be passed to the client's
 *                                       provided notification function. 
 *  @param [in]  pf_nfy_fct     DSM device group notification function.  This function
 *                                       is called when a new device is detected or removed on
 *                                       that  DSM device group.
 *  @param [out]  ph_dsm      Handle to an interface (e.g., a device group)
 *  @note
 *  @see
 *  @return  Return the error code
 *  @retval  DSMR_OK                       DSM handle is returned. 
 *  @retval  DSMR_OUT_OF_HANDLE    No more handle available.
 *  @retval  DSMR_OUT_OF_MEM        Not enough memory to create the DSM control structure.
 *  @retval  DSMR_INV_ARG               'ph_dsm' is NULL or 't_dev_group' is not a valid group.
 *  @retval  DSMR_AEE_OUT_OF_RESOURCES  Can not allocate AEE resources.
 *  @retval  DSMR_AEE_NO_RIGHTS     No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern  INT32  c_dsm_open
(
	DEVICE_TYPE_T    t_dev_group,
    const CHAR*      ps_name,
    VOID*            pv_tag,
    dsm_dev_nfy_fct  pf_nfy_fct,
    HANDLE_T*		 ph_dsm
);

/*------------------------------------------------------------------*/
/*!@brief   Get information on a device group. 
 *  @param [in]  h_dsm_dev:         handle to device group.
 *  @param [in]  t_get_type    specifies the get operation to be performed on
 *                                       the device group.  The set type is device group specific.  
 *  @param [in]  pv_get_info   optional parameters for the get operation.
 *  @param [in]  pz_size         the size of buffer pointed to by the pv_data. 
 *  @param [out] pz_size       the number of valid bytes in the buffer pointed
 *                                      to by the pv_data. 
 *  @param [out] pv_get_data       the data returned by the get operation.
 *  @note
 *  @see
 *  @return  Return the error code
 *  @retval  DSMR_OK           Information about this device is returned
 *  @retval  DSMR_INV_HANDLE   'h_dsm' is a invalid.
 */
/*------------------------------------------------------------------*/

extern  INT32  c_dsm_get
(
    HANDLE_T         h_dsm_dev,
    DSM_GET_T	     t_get_type,
    VOID*            pv_get_info,
    SIZE_T*	         pz_size,
    VOID*            pv_get_data
);

/*------------------------------------------------------------------*/
/*!@brief   Perform set operation on a device group. 
 *  @param [in]  h_dsm_dev    handle to a device group.
 *  @param [in]  t_set_type   specify the set command.	 The set type is 
 *                                      device group specific.  
 *  @param [in]  pv_set_info  Optional parameter for the set command.
 *                    If the 'h_dsm_dev' is a 1394 device group, then
 *                     'pv_set_info' is directly mapped to the 'pv_set_info'
 *                     information required for the FWM (Firewire) set API
 *                    function.
 *
 *                    If the 'h_dsm_dev' is an AVC device group, then this
 *                    argument corresponds to the 'pv_set_info' argument in
 *                    the *(x_rm_set_fct)() function.	
 *  @param [in]  pz_size         the size of buffer pointed to by the pv_set_data. 
 *  @note
 *  @see
 *  @return  Return the error code
 *  @retval  DSMR_OK         Number of records found.
 *  @retval  DSMR_INV_HANDLE Bad 'h_dsm' handle.
 *  @retval  DSMR_INV_ARG    'pui2_num_recs' or 'pui4_ver_id' is a NULL pointer.
 */
/*------------------------------------------------------------------*/

extern  INT32  c_dsm_set
(
    HANDLE_T         h_dsm_dev,
    DSM_SET_T        t_set_type,
    VOID*            pv_set_info,
    SIZE_T           z_size
);

/*------------------------------------------------------------------*/
/*!@brief   This function creates a handle to an instance of source device attached to the system.
 *  @param [in]  h_dsm:	    Handle to the DSM interface which this device type belongs to.
 *  @param [in]  t_dev_type    Specifies the device name belonging to this 'h_dsm' device interface .
 *  @param [in]  ps_name        string to pass to the Resource Manager 
 *  @param [in]  ui2_idx           iterate for next instance of the device of the specified device type name.
 *  @param [in]  pv_tag           Private tag that will be passed to the client's provided notification function. 
 *  @param [in]  pf_dev_nfy_fct    DSM device notification function.  This function
 *                                           will be called in the context of the DSM thread to
 *                                           notify application of any change in the status of
 *                                           the attached device.
 *  @param [out]  ph_dsm_dev        handle to an instance of a device.
 *  @note
 *  @see
 *  @return  Return the error code
 *  @retval  DSMR_OK             DSM handle is returned. 
 *  @retval  DSMR_OUT_OF_HANDLE    No more handle available.
 *  @retval  DSMR_OUT_OF_MEM        Not enough memory to create the DSM control structure.
 *  @retval  DSMR_INV_ARG               'h_dsm' is NULL_HANDLE, 'ph_dsm_dev' is NULL.
 *  @retval  DSMR_INV_HANDLE     'h_dsm' is wrong handle for the interface group
 *                                             that this device belongs to.
 *  @retval  DSMR_AEE_OUT_OF_RESOURCES  Can not allocate AEE resources.
 *  @retval  DSMR_AEE_NO_RIGHTS No right for the AEE resources.
 */
/*------------------------------------------------------------------*/

extern  INT32  c_dsm_dev_open
(
    HANDLE_T         h_dsm,
    DEVICE_TYPE_T    e_dev_type,
    const CHAR*      ps_name,
    UINT16	         ui2_idx,
    VOID*            pv_tag,
    dsm_dev_nfy_fct  pf_dev_nfy_fct,
    HANDLE_T*        ph_dsm_dev
);

/*------------------------------------------------------------------*/
/*!@brief   Get information on an instance of a specific device.
 *  @param [in]  h_dsm_dev     handle to an instance of device.
 *  @param [in]  t_get_type    specifies the get operation to be performed
 *                                       on the specified device.  This flag is defined by
 *                                       specific device.
 *  @param [in]  pv_get_info   optional parameters for the get operation.
 *  @param [in]  pz_size         the size of buffer pointed to by the pv_data. 
 *  @param [out] pz_size       the number of valid bytes in the buffer pointed
 *                                      to by the pv_data. 
 *  @param [out] pz_size       the number of valid bytes in the buffer pointed
 *                                      to by the pv_data. 
 *  @param [out] pz_sizepv_data       the data returned by the get operation.
 *  @note
 *  @see
 *  @return  Return the error code
 *  @retval  DSMR_OK           Data from the specified device is returned. 
 *  @retval  DSMR_INV_HANDLE   ' h_dsm_dev' is invalid.
 */
/*------------------------------------------------------------------*/

extern  INT32  c_dsm_dev_get
(
    HANDLE_T         h_dsm_dev,
    DSM_DEV_GET_T    t_get_type,
    VOID*            pv_get_info,
    SIZE_T*	         pz_size,
    VOID*            pv_get_data
);

/*------------------------------------------------------------------*/
/*!@brief   Perform set operation on an instance of a specified device.
 *  @param [in]  h_dsm_dev     handle to an instance of device.
 *  @param [in]  t_set_type    specify the set command. The set type is
 *                                       device specific.
 *  @param [in]  pv_set_info   Optional parameter for the set command.
 *                  If the 'h_dsm_dev' is a 1394 device, then
 *                  'pv_set_info' is directly mapped to the 
 *                  'pv_set_info' information required for the
 *                   FWM (Firewire) set function.
 *
 *                  If the 'h_dsm_dev' is an AVC device, then this
 *                  argument corresponds to the 'pv_set_info' argument
 *                  in the *(x_rm_set_fct)
 *  @param [in]  pz_size         the size of buffer pointed to by the pv_set_info. 
 *  @note
 *  @see
 *  @return  Return the error code
 *  @retval  DSMR_OK         Number of records found.
 *  @retval  DSMR_INV_HANDLE Bad 'h_dsm' handle.
 */
/*------------------------------------------------------------------*/

extern  INT32  c_dsm_dev_set
(
    HANDLE_T         h_dsm_dev,
    DSM_DEV_SET_T    t_set_type,
    VOID*            pv_set_info,
    SIZE_T           z_size
);

#endif /* _C_DSM_H_ */

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

