/* 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 x_scdb.h 
 *  $File: //DTV/PROD_BR/DTV_X_IDTV1501/apollo/middleware/public/scdb/x_scdb_api.h $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This header file contains stream component database API definitions,
 *         which are exported to other Middleware components and applications.
 *         
 */
/*----------------------------------------------------------------------------*/

#ifndef _X_SCDB_API_H_
#define _X_SCDB_API_H_
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_SCDB
 *  @{
 */
/*----------------------------------------------------------------------------*/

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


#include "u_scdb.h"

/*-------------------------------------------------------------------------
                    functions declarations
 --------------------------------------------------------------------------*/
/*------------------------------------------------------------------*/
/*! @brief  This API returns a handle to the SCDB object for a
 *          specified connection.
 *  @param  [in]  h_connection      - Specifies the connection handle that was
 *                                    used to create the SCDB object.
 *  @param  [in]  pv_tag            - Private tag value associated with the
 *                                    calling client.
 *  @param  [in]  pf_nfy            - Client notification function.
 *  @param  [out] ph_scdb           - pointer to a SCDB handle.
 *  @return Return the error code
 *  @retval SCDBR_OK            - A new handle is created
 *  @retval SCDBR_OUT_OF_HANDLE - No more handle available.
 *  @retval SCDBR_INV_HANDLE    - bad 'h_connection' handle.
 *  @retval SCDBR_OUT_OF_MEM    - Out of memory.
 *  @retval SCDBR_INV_ARG       - ph_scdb is NULL.
 *  @retval SCDBR_NOT_FOUND     - SCDB database for the specified connection is
 *                                not found.
 *  @retval SCDBR_AEE_OUT_OF_RESOURCES  - Can not allocate AEE resources.
 *  @retval SCDBR_AEE_NO_RIGHTS - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern INT32 x_scdb_open
(
    HANDLE_T                  h_connection,
    HANDLE_T*                 ph_scdb,
    VOID*                     pv_tag,
    x_scdb_nfy_fct            pf_nfy
);

/*------------------------------------------------------------------*/
/*! @brief  This API frees the specified handle to the SCDB database.
 *  @param  [in]  h_scdb            - Handle to be freed.
 *  @return Return the error code
 *  @retval SCDBR_OK            - SCDB handle and its resource are free.
 *  @retval SCDBR_INV_HANDLE    - Bad SCDB handle.
 */
/*------------------------------------------------------------------*/
extern INT32 x_scdb_close
(
    HANDLE_T                  h_scdb
);

/*------------------------------------------------------------------*/
/*! @brief  This API get the shared metadata about the records stored
 *          in the SCDB database object.
 *  @param  [in]  h_scdb            - Handle to the SCDB object.
 *  @param  [out] pt_scdb_common    - Pointer to a structure containing SCDB
 *                                    common data.
 *  @return Return the error code
 *  @retval SCDBR_OK            - Common data is copied.
 *  @retval SCDBR_INV_HANDLE    - Bad SCDB handle.
 */
/*------------------------------------------------------------------*/
extern INT32 x_scdb_get_common
(
    HANDLE_T                  h_scdb,
    SCDB_COMMON_T*            pt_scdb_common 
); 


/*------------------------------------------------------------------*/
/*! @brief  This API gets a record with a specified stream type
 *          and stream_id value from the database.
 *  @param  [in]  h_scdb            - Handle to the SCDB object.
 *  @param  [in]  pt_stream_descr   - Pointer to the structure specifying the
 *                                    stream type and stream id.
 *  @param  [out] pt_scdb_rec       - Pointer to the structure containing the
 *                                    stream component data.
 *  @return Return the error code
 *  @retval SCDBR_OK                - A SCDB_REC_T structure is returned.
 *  @retval SCDBR_INV_HANDLE        - Bad 'h_scdb' handle.
 *  @retval SCDBR_INVA_ARG          - 'pt_stream_descr' or 'pt_scdb_rec'
 *                                    is NULL.
 *  @retval SCDBR_REC_NOT_FOUND     - Specified record is not found.
 */
/*------------------------------------------------------------------*/
extern INT32 x_scdb_get_rec
(
    HANDLE_T                  h_scdb,
    const STREAM_COMP_ID_T*   pt_stream_descr,
    SCDB_REC_T*               pt_scdb_rec
);


/*------------------------------------------------------------------*/
/*! @brief  This API gets a record from the SCDB database object. The
 *          record is specified by the stream_type_t value and an index
 *          value.  If the specified 'stream_type_t' is ST_UNKONWN,
 *          then SCDB record matching any stream type is returned to
 *          the caller.
 *          To get the next record, the index counter 'ui2_idx'
 *          is incremented.
 *  @param  [in]  h_scdb            - Client handle.
 *  @param  [in]  e_stream_type     - Specify the stream type.
 *  @param  [in]  ui2_idx           - Index value for selecting the record that
 *                                    match the specified stream type. 0 being
 *                                    the first match, 1 the second match, etc.
 *  @param  [out] pt_stream_descr   - Pointer to a stream descriptor structure
 *                                    holding the stream type and stream id of
 *                                    the record returned.
 *  @param  [out] pt_scdb_rec       - Pointer to a SCDB record.
 *  @param  [out] pui4_db_version   - Current version number of the database.
 *  @see    x_scdb_get_num_recs
 *  @return Return the error code
 *  @retval SCDBR_OK            - A SCDB_REC_T structure is returned.
 *  @retval SCDBR_INV_HANDLE    - Bad 'h_scdb' handle.
 *  @retval SCDBR_INVALIE_ARG   - 'pt_stream_descr' or 'pt_scdb_rec'
 *                                is NULL.
 *  @retval SCDBR_REC_NOT_FOUND - Specified record is not found.
 *  @retval SCDBR_DB_MODIFIED   - Between read operations of the
 *                                stream component database using
 *                                different idx value, the
 *                                records has been modified.  The
 *                                application should re-starts
 *                                the read operation with idx=0
 */
/*------------------------------------------------------------------*/
extern INT32 x_scdb_get_rec_by_idx
(
    HANDLE_T            h_scdb,
    STREAM_TYPE_T       e_stream_type,
    UINT16              ui2_idx,
    STREAM_COMP_ID_T*   pt_stream_descr,
    SCDB_REC_T*         pt_scdb_rec,
    UINT32*             pui4_db_version    
);

/*------------------------------------------------------------------*/
/*! @brief  This API returns the number of records matching the specified
 *          stream type.
 *  @param  [in]  h_scdb            - Handle to the SCDB database.
 *  @param  [in]  e_stream_type     - Specify the stream type.
 *  @param  [out] pui2_num_recs     - Pointer to a variable holding the result.
 *  @param  [out] pui4_db_version   - Current version number of the SCDB
 *                                    database.
 *  @see    x_scdb_get_rec_by_idx
 *  @return Return the error code
 *  @retval SCDBR_OK            - Number of records found is returned.
 *  @retval SCDBR_INV_ARG       - 'pui2_num_recs' is a NULL pointer.
 *  @retval SCDBR_INV_HANDLE    - Bad 'h_scdb' handle.
 */
/*------------------------------------------------------------------*/
extern INT32 x_scdb_get_num_recs
(
    HANDLE_T            h_scdb,
    STREAM_TYPE_T       e_stream_type,
    UINT16*             pui2_num_recs,
    UINT32*             pui4_db_version    
);

/*------------------------------------------------------------------*/
/*! @brief  This function register compare functions for sorting
 *          operation. The compare function are SCDB handle specific.
 *  @param  [in]  h_scdb            - Handle to the SCDB database.
 *  @param  [in]  pv_tag            - Tag for the compare function.
 *  @param  [in]  pf_sort_cmp       - Compare function used for sorting.
 *  @return Return the error code
 *  @retval SCDBR_OK            - Operation is successful.
 *  @retval SCDBR_INV_ARG       - 'pf_sort_cmp' is a NULL pointer.
 *  @retval SCDBR_INV_HANDLE    - Bad 'h_scdb' handle.
 */
/*------------------------------------------------------------------*/
extern INT32 x_scdb_reg_cmp_fcts
(
    HANDLE_T               h_scdb,
    VOID*                  pv_tag,
    x_scdb_sort_cmp        pf_sort_cmp
);

/*----------------------------------------------------------------------------*/
/*! @} */
/*----------------------------------------------------------------------------*/
#endif /* _X_SCDB_API_H_ */
