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

#ifndef _U_LOL_H_
#define _U_LOL_H_
/*----------------------------------------------------------------------------*/
/*! @defgroup   groupMW_LOL Large Object List
 *  @ingroup    groupMW
 *  @brief      The LOL module is used to store and retrieve arbitrary large
 *              binary objects, for example, raw SI table data.
 *  @see        groupMW_CDB
 *  @{
 */
/*----------------------------------------------------------------------------*/

#include "u_common.h"
#include "u_handle.h"
#include "u_handle_grp.h"

#pragma pack(4)
/*--------------------------------------------------------------------------
 Constants, enumerations, and macros
---------------------------------------------------------------------------*/

/* Return code status from API */
#define         LOLR_OK                    ((INT32)  0)    /**< Operation succeeded. */
#define         LOLR_FAIL                  ((INT32) -1)    /**< Operation failed. */
#define         LOLR_OUT_OF_HANDLE         ((INT32) -2)    /**< Handle allocation failed. */
#define         LOLR_OUT_OF_MEM            ((INT32) -3)    /**< Memory exhausted. */
#define         LOLR_INV_HANDLE            ((INT32) -4)    /**< Bad handle. */
#define         LOLR_INV_ARG               ((INT32) -5)    /**< Invalid argument. */
#define         LOLR_REC_NOT_FOUND         ((INT32) -6)    /**< Record not found. */
#define         LOLR_NO_WRITE_LOCK         ((INT32) -7)    /**< Failed initializing RW Lock. */
#define         LOLR_NOT_FOUND             ((INT32) -8)    /**< Specified LOL object not found. */
#define         LOLR_END_OF_ITERATION      ((INT32) -9)    /**< Iteration reached end. */
#define         LOLR_MODIFIED              ((INT32) -10)    /**< Database modified since last iteration. */
#define         LOLR_DUPLICATE_REC         ((INT32) -11)    /**< Existing record with the same key value is found. */
#define         LOLR_INV_FILE_PATH         ((INT32) -12)    /**< Invalid file path. */
#define         LOLR_OUT_OF_SPACE          ((INT32) -13)    /**< Failed to allocate space on file system. */
#define         LOLR_AEE_OUT_OF_RESOURCES  ((INT32) -14)    /**< Can not allocate AEE resources. */
#define         LOLR_AEE_NO_RIGHTS         ((INT32) -15)    /**< No right for the AEE resources. */
#define         LOLR_FILE_READ_FAIL        ((INT32) -16)    /**< Failed to read from file. */
#define         LOLR_FILE_WRITE_FAIL       ((INT32) -17)    /**< Failed to write to file. */
#define         LOLR_INV_FILE_VER          ((INT32) -18)    /**< Incompatible file version. */

/* maximum length of the largest object stored. */
#define         MAX_LARGE_OBJECT_LEN       4096/**< Maximum length of the largest object stored. */

/* handle group type for the Large Object list handle. */
#define         LOLT_LARGE_OBJECT_LIST     (HT_GROUP_LOL + ((HANDLE_TYPE_T) 0))    /**< Handle group type for the Large Object list handle. */

/* Notification conditions. */
/*------------------------------------------------------------------*/
/*! @brief  Notification conditions.
 *  @code
 *  typedef enum
 *  {
 *      LOL_UPDATING,   
 *      LOL_UPDATED,    
 *      LOL_CLOSED,     
 *      LOL_UNKNOWN
 *  }   LOL_COND_T;
 *  @endcode
 *  @li@c  LOL_UPDATING                  - When lol_lock is called.
 *  @li@c  LOL_UPDATED                   - When lol_unlock is called.
 *  @li@c  LOL_CLOSED                    - When lol_delete is called.
 *  @li@c  LOL_UNKNOWN                   - Unknown condition.
 */
/*------------------------------------------------------------------*/
typedef enum
{
    
    LOL_UPDATING,   /* When lol_lock() is called. */
    LOL_UPDATED,    /* When lol_unlock() is called. */
    LOL_CLOSED,     /* When lol_delete() is called. */
    LOL_UNKNOWN
    
}   LOL_COND_T;

/* prototype for the notification. */
/*------------------------------------------------------------------*/
/*! @brief  Prototype for the notification.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  e_cond            - The status flag for the LOL object.
 *  @param  [in]  ui4_reason        - The reason for the notification.
 *  @param  [in]  pv_tag            - Private tag for the client.
 *  @param  [in]  ui4_data          - Data pass back to the application.
 *  @note   It is very important that the client MUST NOT try to read the LOL in
 *          the context of notification function.  Otherwise, a `Dead lock'
 *          situation would arise.  The client should only send a message to
 *          itself from the notification function or set a condition flag, and
 *          execute the read operation outside the context of the notification
 *          function.
 *          @par
 *          Client should also avoid doing CPU intensive task in the
 *          notification function.  If CPU intensive task needs to be performed,
 *          then the notification function should send a message to the client
 *          thread, and have the CPU intensive task executed in the client
 *          thread context.
 *  @see    c_lol_create, c_lol_open, c_lol_open_by_name, c_lol_fs_load
 *  @return None
 */
/*------------------------------------------------------------------*/
typedef VOID (*x_lol_nfy_fct) (HANDLE_T          h_lol,
                               LOL_COND_T        e_cond,
                               UINT32            ui4_reason,
                               VOID*             pv_tag,
                               UINT32            ui4_data);

/* Notification reasons */
#define LOL_REASON_UNKNOWN  ((UINT32)( 0x0000 ))   /**< Reason unknown */
#define LOL_RECORD_ADD      MAKE_BIT_MASK_32(1)    /**< Reason for adding records */
#define LOL_RECORD_DEL      MAKE_BIT_MASK_32(2)    /**< Reason for deleting records */
#define LOL_RECORD_MOD      MAKE_BIT_MASK_32(3)    /**< Reason for modifying records */

/* Maximum length for a name specifying a Large Object List object. */
#define     MAX_LOL_NAME_LEN    32    /**< Maximum length for a name specifying a Large Object List object. */

#define     LOL_NULL_ID         (0)    /**< NULL LOL ID value. */

/* specified null record id value.  Note:
   valid large object record id is from 1 to 2**16
*/
#define     LOL_NULL_REC_ID     ((UINT16)0)    /**< NULL record ID value. Note: valid large object record id is from 1 to 2**16 */

#define     LOL_NULL_VER_ID     ((UINT32)0)    /**< Null LOL database version id. */


/* Typedef and constants for LOL record id query flag. */
typedef     UINT8                 LOL_REC_ID_QRY_T;    /**< Typedef for LOL record id query flag. */

#define     LOL_FIRST_REC_ID      ((LOL_REC_ID_QRY_T) 1)    /**< First record ID. */
#define     LOL_LAST_REC_ID       ((LOL_REC_ID_QRY_T) 2)    /**< Last record ID. */
#define     LOL_NEXT_REC_ID       ((LOL_REC_ID_QRY_T) 3)    /**< Next record ID. */

/* Typedef and constants for LOL record iteration flag. */
typedef	    UINT8                 LOL_ITERATE_T;    /**< Typedef for LOL record iteration flag. */

#define     LOL_NEXT_REC          ((LOL_ITERATE_T) 1)    /**< Next record */
#define     LOL_PREV_REC          ((LOL_ITERATE_T) 2)    /**< Previous record */
#define     LOL_FIRST_REC         ((LOL_ITERATE_T) 3)    /**< First record */
#define     LOL_LAST_REC          ((LOL_ITERATE_T) 4)    /**< Last record */

/* Typedef and constants for lol data tag flag .*/
typedef     UINT32                LOL_DATA_TAG_T;        /**< Typedef for LOL data tag flag. */
#define     LOL_DATA_TAG_TP_UNIVER      ((LOL_DATA_TAG_T)1) /**< for saving satellite's TP info when antenna type is Universal */
#define     LOL_DATA_TAG_TP_SINGCAB     ((LOL_DATA_TAG_T)2) /**< for saving satellite's TP info when antenna type is singleCable  */
#define     LOL_DATA_TAG_DVBS_BGM_INFO  ((LOL_DATA_TAG_T)3) /**< for saving dvbs BGM info  */
#define     LOL_DATA_TAG_DVBS_MON_INFO  ((LOL_DATA_TAG_T)4) /**< for saving dvbs monitor info  */
#define     LOL_DATA_TAG_DVBS_SB_INFO_UNIVER  ((LOL_DATA_TAG_T)5) /**< for saving dvbs SB info: UNIVER  */
#define     LOL_DATA_TAG_DVBS_SB_INFO_SINGCAB ((LOL_DATA_TAG_T)6) /**< for saving dvbs SB info: SINGCAB */
#define     LOL_DATA_TAG_DVBS_CONFIG_INFO     ((LOL_DATA_TAG_T)7) /**< for saving dvbs scan config to LOL */       
#define     LOL_DATA_TAG_DVBS_TKGS_HIDDEN_LOCATION  ((LOL_DATA_TAG_T)8) /**< for saving dvbs TKGS hidden location */
#define     LOL_DATA_TAG_DVBS_TKGS_VISIBLE_LOCATION  ((LOL_DATA_TAG_T)9) /**< for saving dvbs TKGS visible location */
#define     LOL_DATA_TAG_DVBS_TKGS_CATEGORY_INFO     ((LOL_DATA_TAG_T)10) /**< for saving dvbs TKGS categoty info */
#define     LOL_DATA_TAG_DVBS_TKGS_SVC_LIST_INFO     ((LOL_DATA_TAG_T)11) /**< for saving dvbs TKGS service list info */
#define     LOL_DATA_TAG_DVBS_TKGS_SAVE_USR_MSG      ((LOL_DATA_TAG_T)12) /**< for saving dvbs TKGS user message */
#define     LOL_DATA_TAG_DVBT_LCN_CONFLICT           ((LOL_DATA_TAG_T)13) /**< for saving dvbt lcn conflict data */

/* Extend */
#define     LOL_DATA_TAG_DVBS_CATEGORY_INFO          LOL_DATA_TAG_DVBS_TKGS_CATEGORY_INFO /**< for saving dvbs category info */   


/*------------------------------------------------------
  data structure and typedef.
------------------------------------------------------*/

/* Structure for the LOL data record */
/*------------------------------------------------------------------*/
/*!  @brief  Structure for the LOL data record
 *  @code
 *  typedef struct _LOL_REC_T
 *  {
 *      UINT32        ui4_data_tag;
 *  	UINT16        ui2_lol_rec_id;
 *      UINT16        ui2_data_len; 
 *      UINT8         aui1_data[MAX_LARGE_OBJECT_LEN];
 *  } LOL_REC_T;
 *  @endcode
 *  @li@c  ui4_data_tag                  - Large Object data tag.
 *  @li@c  ui2_lol_rec_id                - LOL record id.
 *  @li@c  ui2_data_len                  - Large Object data length.
 *  @li@c  aui1_data                     - Large Object data.
 */
/*------------------------------------------------------------------*/
typedef struct _LOL_REC_T
{
    /* Tag */
    UINT32        ui4_data_tag;

    /* LOL record id */
	UINT16        ui2_lol_rec_id;

    UINT16        ui2_data_len;

    /* Large Object data */
    UINT8         aui1_data[MAX_LARGE_OBJECT_LEN];

} LOL_REC_T;

#define  LOL_REC_SIZE (4+2+2+MAX_LARGE_OBJECT_LEN)    /**< Pre-set size of the LOL record structure. */


typedef  UINT8       LOL_MEM_POLICY_T;    /**< Typedef for LOL memory mangement policy. */

#define  LOL_MEM_STATIC   ((LOL_MEM_POLICY_T) 0)    /**< Static memory policy. */
#define  LOL_MEM_DYNAMIC  ((LOL_MEM_POLICY_T) 1)    /**< Dynamic memory policy. */

/*
 * Structure for memory dump.
 */
/*------------------------------------------------------------------*/
/*!  @brief  Structure for memory dump.
 *  @code
 *  typedef struct _LOL_MEM_DUMP_T_
 *  {
 *      UINT16      ui2_lol_id;
 *      CHAR        ps_lol_name[MAX_LOL_NAME_LEN+1];
 *      VOID*       pv_data;
 *      UINT32      ui4_data_len;
 *  }  LOL_MEM_DUMP_T ;
 *  @endcode
 *  @li@c  ui2_lol_id                    - ID of the Large Object List
 *  @li@c  ps_lol_name                   - Name of the Large Object List
 *  @li@c  pv_data                       - Memory dump of LOL database
 *  @li@c  ui4_data_len                  - Size of memory allocated for pv_data
 */
/*------------------------------------------------------------------*/
typedef struct _LOL_MEM_DUMP_T_
{
    UINT16      ui2_lol_id;
    CHAR        ps_lol_name[MAX_LOL_NAME_LEN+1];
    VOID*       pv_data;
    UINT32      ui4_data_len;
}  LOL_MEM_DUMP_T ;


/*typedef union _UNION_POINTER_T
{
	void* value;
	uint32_t compat_value;
	uint64_t sizer;
}UNION_POINTER_T;*/

typedef struct _LOL_MEM_DUMP_EX_T_
{
    UINT16      	 ui2_lol_id;
    CHAR        	 ps_lol_name[MAX_LOL_NAME_LEN+1];
    UNION_POINTER_T  pv_data; // VOID*
    UINT32      ui4_data_len;
}  LOL_MEM_DUMP_EX_T ; 

/*
  typedef for LOL user defined compare function that implement customized
  sorting order of LOL record.  This function is called during the
  sorting operation.
*/
/*------------------------------------------------------------------*/
/*! @brief  Typedef for LOL user defined compare function that implement
 *          customized sorting order of LOL record.  This function is called
 *          during the sorting operation.
 *  @param  [in]  pt_lol_rec_1      - Reference a LOL record structure.
 *  @param  [in]  pt_lol_rec_2      - Reference a LOL record structure.
 *  @param  [in]  pv_tag            - Private tag info pass to the comparison
 *                                    function.
 *  @return Comparison result
 *  @retval RC_SMALLER          - `pt_lol_rec_1' is less than `pt_lol_rec_2'.
 *  @retval RC_EQUAL            - `pt_lol_rec_1' is equal to  `pt_lol_rec_2'.
 *  @retval RC_GREATER          - `pt_lol_rec_1' is greater than `pt_lol_rec_2'.
 */
/*------------------------------------------------------------------*/
typedef INT32 (*x_lol_sort_cmp)
(
    const LOL_REC_T*     pt_lol_rec_1,
    const LOL_REC_T*     pt_lol_rec_2,
    VOID*                pv_tag
);

/*
  typedef for LOL user defined search compare function. This
  function will be called by the LOL library when performing
  binary search operation on sorted LOL records.
  For binary search operation, this function must implement the
  same logic order as implemented by the x_lol_sort_cmp function.
*/
/*------------------------------------------------------------------*/
/*! @brief  Typedef for LOL user defined search compare function. This
 *          function will be called by the LOL library when performing
 *          binary search operation on sorted LOL records.
 *          For binary search operation, this function must implement the
 *          same logic order as implemented by the x_lol_sort_cmp function.
 *  @param  [in]  pt_lol_rec        - Reference a LOL record structure.
 *  @param  [in]  pv_data_to_compare - Value parameter to compare with LOL
 *                                     record `pt_lol_rec'.
 *  @param  [in]  pv_tag            - Private tag info pass to the comparison
 *                                    function.
 *  @return Comparison result
 *  @retval RC_SMALLER      - `pt_lol_rec_1' is less than `pv_data_to_compare'.
 *  @retval RC_EQUAL        - `pt_lol_rec_1' is equal to `pv_data_to_compare'.
 *  @retval RC_GREATER      - `pt_lol_rec_1' is greater than `pt_lol_rec_2'.
 */
/*------------------------------------------------------------------*/
typedef INT32 (*x_lol_search_cmp)
(
    const LOL_REC_T*     pt_lol_rec,
    const VOID*          pv_data_to_compare,
    VOID*                pv_tag
);


/*----------------------------------------------------------------------------*/
/*! @} */
/*----------------------------------------------------------------------------*/
#pragma pack()

#endif  /* _U_LOL_H_ */
