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

#ifndef _C_CDB_API_H_
#define _C_CDB_API_H_
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_CDB
 *  @{
 */
/*----------------------------------------------------------------------------*/

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

/*------------------------------------------------------------------*/
/*! @brief  This API creates a database object and client object that
 *          points to the database object.
 *  @param  [in]  ui2_max_record    - maximum number of records for this
 *                                    database object.(STATIC), or it is
 *                                    the chunk size when internal
 *                                    memory is increased (DYNAMIC)
 *  @param  [in]  e_memory_policy   - memory policy (STATIC or DYNAMIC)
 *  @param  [in]  s_db_name         - database name
 *  @param  [in]  ui1_count         - count of the record fields
 *  @param  [in]  at_field_info     - record field description array
 *  @param  [in]  ui1_key_field_count   - count of number of field that
 *                                        makes up the key parameter
 *  @param  [in]  aui4_key_field_types  - array of field types that makes
 *                                        up the key parameter
 *  @param  [in]  pv_tag            - a tag specified by the client
 *  @param  [in]  pf_nfy            - a notification provide by the client.
 *                                    This notification funciton is called to
 *                                    notify the registered client any changes
 *                                    in the database object
 *  @param  [out] ph_client         - A client handle to the database object
 *  @see    c_db_get_handle_by_name
 *  @return Return the error code
 *  @retval DBR_OK              - A new database object and a client handle to
 *                                the database object are initialized
 *                                successfully.
 *  @retval DBR_FAIL            - Cannot create database object and handle.
 *  @retval DBR_INV_ARG         - Input arguments are invalid, either because
 *                                the count variables are equal to 0 or the
 *                                pointer variables are null.
 *  @retval DBR_OUT_OF_MEMORY   - Out of memory.
 *  @retval DBR_OUT_OF_HANDLE   - Out of handle.
 *  @retval DBR_DB_LIMIT_EXCEED - Can not create anymore database object,
 *                                because we have reach the resouce limit.
 *  @retval DBR_INV_NAME        - The Specified name 's_db_name' has been used
 *                                by another CDB object.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_create
(
    UINT16            ui2_max_record,
    DB_MEM_POLICY_T   e_memory_policy,
    CHAR*             s_db_name,
    UINT8             ui1_count,
    DB_FIELD_INFO_T   at_field_info[],
    UINT8			  ui1_key_field_count,
    DB_FIELD_T        aui4_key_field_types[],
    VOID*             pv_tag,
    db_notify_fct     pf_nfy,
    HANDLE_T*         ph_client
);


/*------------------------------------------------------------------*/
/*! @brief  This API delete a named database object all the handles
 *          (e.g, the owner that create the database and other
 *          client handles that point to this database.)
 *  @param  [in]  h_client      - handle to the database object.
 *  @param  [in]  s_db_name     - specifies the name of the database object.
 *  @return Return the error code
 *  @retval DBR_OK          - Specified database object is deleted.
 *  @retval DBR_NOT_FOUND   - Cannot find the specified database object.
 *  @retval DBR_INV_HANDLE  - Bad handle.
 *  @retval DBR_INV_ARG     - s_db_name is null.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_delete
(
    HANDLE_T          h_client,
    CHAR*             s_db_name
);

/*------------------------------------------------------------------*/
/*! @brief  This API delete all records from a specified database object.
 *  @param  [in]  h_client      - handle to the database object.
 *  @return Return the error code
 *  @retval DBR_OK          - All records from the specified database
 *                            object are deleted.
 *  @retval DBR_INV_HANDLE  - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_clean
(
    HANDLE_T          h_client
);

/*------------------------------------------------------------------*/
/*! @brief  This API returns a new client handle to a database.
 *  @param  [in]  s_db_name     - Name of the database object.
 *  @param  [in]  pv_tag        - A private tag value for this client.
 *  @param  [in]  pf_nfy        - Notification for this client.
 *  @param  [out] ph_client     - A handle to the database object.
 *  @see    c_db_create
 *  @return Return the error code
 *  @retval DBR_OK          - A new handle to the specified database object is
 *                            created.
 *  @retval DBR_NOT_FOUND   - The specified database object does not existed.
 *  @retval DBR_OUT_OF_HANDLE - Cannot create a new handle to the database
 *                            object.
 *  @retval DBR_INV_ARG     - s_db_name or ph_client is null.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_get_handle_by_name
(
    CHAR*             s_db_name,
    VOID*             pv_tag,
    db_notify_fct     pf_nfy,
    HANDLE_T*         ph_client
);

/*------------------------------------------------------------------*/
/*! @brief  This API reads a specific record from the database record.
 *  @param  [in]  h_client          - handle to the database client
 *  @param  [in]  ui1_keyfld_count  - number of fields that make up the search
 *                                    parameters.
 *  @param  [in]  aui4_keyfld_types - field types that make up the search
 *                                    paramters.
 *  @param  [in]  apv_keyfld_addrs  - an array of pointers to the content of
 *                                    the search parameters.
 *  @param  [in]  at_keyfld_search_opts - pointer to an array of DB_SEARCH_T
 *                                        options.
 *  @param  [in]  ui1_count         - number of value to be extracted
 *  @param  [in]  aui4_fld_type_selected - field types to be obtained.
 *  @param  [in]  ui2_record_index  - index number of the records matching the
 *                                    search paramters.
 *  @param  [in]  aui2_buffer_len   - Specify the buffer space for the buffer
 *                                    ref'd by the address entry in
 *                                    'apv_fld_value_buffer'
 *  @param  [out] apv_fld_value_buffer  - array of pointer address to store the
 *                                        field values.
 *  @param  [out] aui2_buffer_len   - On return, it contains the data len copied
 *                                    into the space ref'd by the the address
 *                                    entry in'apv_fld_value_buffer'.
 *  @param  [out] pui4_db_version   - pointer to current database version id.
 *  @return Return the error code
 *  @retval DBR_OK              - A record is read successfully.
 *  @retval DBR_INV_HANDLE      - Bad handle or the database has been deleted.
 *  @retval DBR_INV_ARG         - Input arguments are invalid, either because
 *                                the count variables are equal to 0 or the
 *                                pointer variables are null.
 *  @retval DBR_REC_NOT_FOUND   - No record matching the searching parameters
 *                                was found.
 *  @retval DBR_MODIFIED        - When reading the database using idx value
 *                                greater than 0, e.g, iterating through the
 *                                records, the database has been modified by
 *                                another client.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_read_rec
(
    HANDLE_T          h_client,
    UINT8		      ui1_keyfld_count,
    const DB_FIELD_T  aui4_keyfld_types[],
    const VOID*       apv_keyfld_addrs[],
    const DB_SEARCH_T at_keyfld_search_opts[],
    UINT8             ui1_count,
    const DB_FIELD_T  aui4_fld_type_selected[],
    VOID*             apv_fld_value_buffer[],
    UINT16            aui2_buffer_len[],
    UINT16            ui2_record_index,
    UINT32*           pui4_db_version
);

/*------------------------------------------------------------------*/
/*! @brief  This API updates fields of an existing record in the
 *          database object.  The record to be updated is specified
 *          by the key fields, and it is an error if the specified
 *          record can not be found.
 *  @param  [in]  h_client          - client handle
 *  @param  [in]  apv_key_field_values  - values for the key parameter.
 *  @param  [in]  ui1_fld_count     - Number of record fields to be updated.
 *  @param  [in]  aui4_fld_type_selected - Specify field type of the record
 *                                         fields to be updated.
 *  @param  [in]  apv_fld_buffer    - Address of the record fields. The content
 *                                    of the address will be copy into the
 *                                    corresponding field in the database
 *                                    record.
 *  @param  [in]  aui2_buffer_len   - Specify the length (in bytes) of data in
 *                                    the buffer ref'd by the address entry in
 *                                    'apv_fld_buffer'
 *  @note   For apv_key_field_values, if multiple fields make up a key
 *          parameter, the order of values has to be in the same order
 *          that key types are specified when the database was created.
 *  @return Return the error code
 *  @retval DBR_OK              - Record is updated successfully.
 *  @retval DBR_INV_HANDLE      - Bad handle.
 *  @retval DBR_INV_ARG         - key_field_values or field_values array is
 *                                null.
 *  @retval DBR_REC_NOT_FOUND   - The specified record can not be found.
 *  @retval DBR_FAIL            - The specified field types does not match the
 *                                record's field types.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_update_rec
(
    HANDLE_T          h_client,
    const VOID*       apv_key_field_values[],
    UINT8             ui1_fld_count,
    const DB_FIELD_T  aui4_fld_type_selected[],
    const VOID*       apv_fld_buffer[],
    const UINT16      aui2_buffer_len[]
);

/*------------------------------------------------------------------*/
/*! @brief  This API write a record into the database object.
 *  @param  [in]  h_client              - client handle
 *  @param  [in]  apv_key_field_values  - values for the key parameter.
 *  @param  [in]  apv_field_values      - values of the record fields.
 *  @param  [in]  aui2_buffer_len       - Specify the length (in bytes) of data
 *                                        in the buffer ref'd by the address
 *                                        entry in 'apv_field_values'
 *  @param  [in]  ui1_write_mode        - Specify if the record to be written
 *                                        is a new record or update an existing
 *                                        record.
 *  @note   For apv_key_field_values, if multiple fields make up a key
 *          parameter, the order of values has to be in the same order
 *          that key types are specified when the database was created.
 *  @return Return the error code
 *  @retval DBR_OK              - Record is written successfully.
 *  @retval DBR_INV_HANDLE      - Bad handle.
 *  @retval DBR_INV_ARG         - key_field_values or field_values array is
 *                                null.
 *  @retval DBR_REC_NOT_FOUND   - The specified record can not be found.
 *  @retval DBR_OUT_OF_MEMORY   - Can not allocate new memory.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_write_rec
(
    HANDLE_T          h_client,
    const VOID*       apv_key_field_values[],
    const VOID*       apv_field_values[],
    const UINT16      aui2_buffer_len[],
    DB_CTRL_FLAG_T    ui1_write_mode
);

/*------------------------------------------------------------------*/
/*! @brief  This API deletes a specific records that matches the
 *          specified search key parameter (field types and
 *          field values)
 *  @param  [in]  h_client             - handle to the client object.
 *  @param  [in]  ui1_key_field_count  - number of fields that makes up the key
 *  @param  [in]  aui4_field_types     - array of field types that makes up the
 *                                       key.
 *  @param  [in]  apv_field_values     - field values for the key parameter.
 *  @param  [in]  ui2_record_index     - The number of record matching the
 *                                       search parameter to delete.  For
 *                                       example: 0 means delete the first
 *                                       record that matches the key parameter,
 *                                       2 means delete third records that
 *                                       matches the key paramter.
 *
 *  @note   For apv_key_field_values, if multiple fields make up a key
 *          parameter, the order of values has to be in the same order
 *          that key types are specified when the database was created.
 *  @return Return the error code
 *  @retval DBR_OK              - Record is successfully deleted.
 *  @retval DBR_REC_NOT_FOUND   - The specified record can not be found.
 *  @retval DBR_INV_HANLDE      - The specified handle is not valid.
 *  @retval DBR_INV_ARG         - key_field_count = 0, or key field types array
 *                                or key_field_values array is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_delete_rec
(
    HANDLE_T          h_client,
    UINT8		      ui1_key_field_count,
    const DB_FIELD_T  aui4_field_types[],  
    const VOID*       apv_field_values[],     
    UINT16		      ui2_record_index 
);

/*------------------------------------------------------------------*/
/*! @brief  This API locks the database before write operations.
 *  @param  [in]  h_client          - handle to the client object.
 *  @see    c_db_write_unlock
 *  @return Return the error code
 *  @retval DBR_OK              - The write lock is acquired successfully.
 *  @retval DBR_INV_HANLDE      - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_write_lock
(
    HANDLE_T h_client
);

/*------------------------------------------------------------------*/
/*! @brief  This API unlocks the database after write operations.
 *  @param  [in]  h_client          - handle to the client object.
 *  @see    c_db_write_lock
 *  @return Return the error code
 *  @retval DBR_OK              - The write lock is released successfully.
 *  @retval DBR_INV_HANLDE      - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_write_unlock
(
    HANDLE_T h_client
);

/*------------------------------------------------------------------*/
/*! @brief  This API locks database for read operation.
 *  @param  [in]  h_client          - handle to the client object.
 *  @see    c_db_read_unlock
 *  @return Return the error code
 *  @retval DBR_OK              - A read lock is acquired successfully.
 *  @retval R_INV_HANDLE        - Bad handle (or the database object is
 *                                deleted.)
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_read_lock
(
    HANDLE_T h_client
);

/*------------------------------------------------------------------*/
/*! @brief  This API unlocks database for read operation.
 *  @param  [in]  h_client          - handle to the client object.
 *  @see    c_db_read_lock
 *  @return Return the error code
 *  @retval DBR_OK              - A read lock is released successfully.
 *  @retval R_INV_HANDLE        - Bad handle (or the database object is
 *                                deleted.)
 */
/*------------------------------------------------------------------*/
extern INT32 c_db_read_unlock
(
    HANDLE_T h_client
);

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