/* 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_sort_search.h
 * $Revision: #1 $
 * $Date: 2015/05/29 $
 * $Author: brianpc.huang $
 *
 * @par Description: 
 *    This header file contains utility API to get SCDB stream
 *    infomation 
 *         
 *---------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_UTIL
  *  @{  
  */
/*----------------------------------------------------------------------------*/
#ifndef _C_UTIL_SCDB_H_
#define _C_UTIL_SCDB_H_

/*---------------------------------------------------------------------------
                    include files
----------------------------------------------------------------------------*/
#include "u_handle.h"
#include "u_scdb.h"
/*-------------------------------------------------------------------------
                    functions declarations
 --------------------------------------------------------------------------*/

/*

   Return the number of PID and the PID values found for that
   specified stream type.
*/
/*----------------------------------------------------------------------------*/
/* ! @brief: This API return the all the PID values associated with a
*              particular stream type.
*
*   @param [in] h_scdb:              Handle to SCDB
*   @param [in] e_stream_type   Specifies the stream type [ST_TELETEXT, ST_SUBTITLE,  ST_CLOSED_CAPTION, ST_AUDIO, ST_VIDEO]
*   @param [in] pui2_sz_array    The size of array (number of elements) in the 'pui4_pid_array'.
*   @param [out]  pui2_pid_array Array with PID valus found for specified stream type.
*   @param [out] pui2_sz_array  Contains the number of PID values filled in the
*                   'pui2_pid_array'.  If the array is too small (return
*                   code 'SCDBR_BUF_TOO_SMALL') to hold all the PID values
*                   found for this stream type, then
*                   it return the size of array needed to store PIDs found
*                   for this stream type (this value is maximum size needed
*                   to store the PID value, so it might be bigger than
*                   actual number of PID found)
*
*   @param [out] pui4_ver_id   The version id of current SCDB database.
*   @retval SCDBR_OK           Success.
*   @retval SCDBR_INV_HANDLE   h_scdb is invalid handle.
*   @retval SCDBR_INV_ARG      'pui2_pid_array' is NULL, or 'pui2_sz_array' is 0,
*                      'pui4_ver_id' is NULL.
*   @retval SCDBR_DB_MODIFIED   Database object is being modified, caller should try
*                       again.
*   @retval SCDBR_BUF_TOO_SMALL  'pui2_pid_array' is not large enough to hold the
*                        all the PID values for this stream type.
*
----------------------------------------------------------------------------*/
extern INT32 c_util_scdb_get_stream_pid_info
(
    HANDLE_T             h_scdb,
    STREAM_TYPE_T        e_type,
    UINT16*              pui2_pid_array,
    UINT16*              pui2_num_pid,
    UINT32*              pui4_ver_id
); 

/*
   Return the SCDB records for a specified stream type and PID.
*/

/*-------------------------------------------------------------------------*/
/*! @brief  Return the SCDB records for a specified stream type
 *              and PID. If specified PID is 0x1FFF, then it is considered
 *              as a 'wild card', and all records for that stream type
 *              are returned.
 *
 *  @param [in] h_scdb              Handle to SCDB
 *   @param [in] e_stream_type  Specifies the stream type [ST_TELETEXT, ST_SUBTITLE,
 *                   ST_CLOSED_CAPTION, ST_AUDIO, ST_VIDEO]
 *   @param [in] ui2_pid        Specifies the PID value.
 *   @param [in] pui2_sz_array   The size of array (number of elements) in the  'at_scdb_records'.
 *   @param [out] at_scdb_records The size of array (number of elements) in the  'pui4_pid_array'.
 *   @param [out] pui2_sz_array  Contains the number of records filled in the
 *                   'at_scdb_records'.  If the array is too small to hold
 *                   all the records found for this stream type, then
 *                   it return the size of array needed to hold all the
 *                   records. 
 *   @param [out] pui4_ver_id    The version id of current SCDB database.
 *  @retval SCDBR_OK            Success. 
 *  @retval  SCDBR_INV_HANDLE    h_scdb is invalid handle.
 *  @retval  SCDBR_INV_ARG      'at_scdb_records' is NULL, or 'pui2_sz_array' is 0, 'pui4_ver_id' is NULL. 
 *  @retval  SCDBR_DB_MODIFIED   Database object is being modified, caller should try again.
 *  @retval  SCDBR_BUF_TOO_SMALL  'at_scdb_array' is not large enough to hold the
 *                        all the PID values for this stream type.
 *
 --------------------------------------------------------------------------*/
extern INT32 c_util_scdb_get_stream_info
(
    HANDLE_T             h_scdb,
    STREAM_TYPE_T        e_type,
    UINT16               ui2_pid,
    SCDB_REC_T*          at_scdb_records,
    UINT16*              pui2_size_array,
    UINT32*              pui4_ver_id
);

#endif /* _C_UTIL_SCDB_H_ */


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

