/* 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_lol.h 
 *  $File: //DTV/MP_BR/DTV_X_IDTV1501_002288_8_001_800_002/apollo/middleware/public/lol/c_lol.h $
 *  $Revision: #1 $
 *  $Date: 2015/11/10 $
 *  $Author: dtvbm11 $
 *  
 *  @par Description:
 *         This header file contains Large Object list related API definitions,
 *         which are exported to applications.
 *
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_LOL_H_
#define _C_LOL_H_
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_LOL
 *  @{
 */
/*----------------------------------------------------------------------------*/

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

#include "u_lol.h"


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

/*------------------------------------------------------------------*/
/*! @brief  Create a LOL object and return a handle to this LOL object.
 *  @param  [in]  ps_lol_name       - Name of the LOL object.
 *  @param  [in]  ui2_lol_id        - Unique id for the LOL object.
 *                                    The limit for LOL ID is between 1 and
 *                                    65535.
 *  @param  [in]  e_mem_policy      - Memory policy: LOL_MEM_STATIC or
 *                                    LOL_MEM_DYNAMIC
 *  @param  [in]  ui2_max_nb_rec    - Specifies the maximum number of LOL record
 *                                    (for LOL_MEM_STATIC), or it specifies
 *                                    number of LOL records per memory chunk.
 *  @param  [in]  pv_tag            - Pointer to a private tag value provided
 *                                    by the caller.  This tag value is passed
 *                                    to the caller's notification function.
 *  @param  [in]  pf_nfy            - Notification function provided by the
 *                                    caller.  This function is called to notify
 *                                    the owner of this LOL handle when the LOL
 *                                    object has been modified.  If NULL, then
 *                                    no notification function will be called.
 *  @param  [out] ph_lol            - Handle to the LOL object.
 *  @see    c_lol_open
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL object is created successfully.
 *  @retval LOLR_INV_ARG        - 'ui2_lol_id' is 0, or ph_lol is NULL, or
 *                                ps_lol_name is 0.
 *  @retval LOLR_OUT_OF_HANDLE  - Cannot get a handle.
 *  @retval LOLR_FAIL           - The specified 'ps_lol_name' or 'ui2_lol_id'
 *                                value is not unique (e.g., it is currently
 *                                been used), or limit of the number of LOL
 *                                objects that can be created is reached.
 *  @retval LOLR_OUT_OF_MEM     - Not enough memory to create LOL object.
 *  @retval LOLR_INV_ARG        - 'ps_lol_name' or 'ph_lol' is NULL.
 *  @retval LOLR_AEE_OUT_OF_RESOURCES   - Can not allocate AEE resources.
 *  @retval LOLR_AEE_NO_RIGHTS  - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_create (const CHAR*       ps_lol_name,
                           UINT16            ui2_lol_id,
                           LOL_MEM_POLICY_T  e_mem_policy,
                           UINT16            ui2_max_nb_rec,
                           VOID*             pv_tag,
                           x_lol_nfy_fct     pf_nfy,
                           HANDLE_T*         ph_lol);

/*------------------------------------------------------------------*/
/*! @brief  This API deletes the specified LOL object associated
 *          with 'h_lol' handle.    Other clients with a handle to
 *          the deleted LOL object will receive a notification of
 *          the delete event.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @return Return the error code
 *  @retval LOLR_OK             - Specified LOL object is deleted.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_delete (HANDLE_T  h_lol);

/*------------------------------------------------------------------*/
/*! @brief  This function gets a handle to the specified LOL database
 *          object by its ID value.
 *  @param  [in]  ui2_lol_id        - Specifies the LOL object identifier value.
 *                                    The limit for LOL ID is between 1 and
 *                                    65535.
 *  @param  [in]  pv_tag            - A private tag value associated with the
 *                                    calling client.
 *  @param  [in]  pf_nfy            - Pointer to the caller provided
 *                                    notification function.  The notification
 *                                    function will be called in the context of
 *                                    the thread that modifies (update, add,
 *                                    delete) the LOL database.  If NULL, then
 *                                    no notification function will be called.
 *  @param  [out] ph_lol            - Pointer to the handle created.
 *  @see    c_lol_open_by_name
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL handle is returned.
 *  @retval LOLR_OUT_OF_HANDLE  - No more handle available.
 *  @retval LOLR_OUT_OF_MEM     - Not enough memory to create the LOL control
 *                                structure.
 *  @retval LOLR_NOT_FOUND      - The specified LOL database object id (e.g.
 *                                'ui2_lol_id') is not found.
 *  @retval LOLR_INV_ARG        - 'ph_lol' is NULL.
 *  @retval LOLR_AEE_OUT_OF_RESOURCES   - Can not allocate AEE resources.
 *  @retval LOLR_AEE_NO_RIGHTS  - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_open (UINT16         ui2_lol_id,
                         VOID*          pv_tag,
                         x_lol_nfy_fct  pf_nfy,
                         HANDLE_T*      ph_lol);

/*------------------------------------------------------------------*/
/*! @brief  This function frees the specified handle to the LOL
 *          database object.
 *  @param  [in]  h_lol             - Handle to LOL database object.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL handle is freed.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_close (HANDLE_T  h_lol);

/*------------------------------------------------------------------*/
/*! @brief  This API removes all the large object records from the
 *          specified LOL object pointed to by the 'h_lol' handle.
 *          All other handles to this LOL object will receive a
 *          notification.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @return Return the error code
 *  @retval LOLR_OK             - All records are successfully removed.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_clean (HANDLE_T  h_lol);

/*------------------------------------------------------------------*/
/*! @brief  This function adds a new large object record to the LOL
 *          database object.  The LOL library will make copy of
 *          the record content from the address location pointed to
 *          by the 'pt_lol_rec'.  The 'ui2_lol_rec_id' field in
 *          the 'pt_lol_rec' structure specifies the key field of the
 *          large object record to be added to the database.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  pt_lol_rec        - Pointer to the large object record structure
 *                                    to be added.
 *  @return Return the error code
 *  @retval LOLR_OK             - Record is successfully added.
 *  @retval LOLR_INV_HANDLE     - Bad LOL handle.
 *  @retval LOLR_OUT_OF_MEM     - Can not allocate memory, add record failed.
 *  @retval LOLR_INV_ARG        - 'pt_lol_rec' is null.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_add_rec  (HANDLE_T          h_lol,
                             const LOL_REC_T*  pt_lol_rec);

/*------------------------------------------------------------------*/
/*! @brief  This function deletes a specified large object record from
 *          the LOL.  The record to be deleted is specified by the
 *          large object record id.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  ui2_lol_rec_id    - Specifies the large object record to
 *                                    be deleted.
 *  @return Return the error code
 *  @retval LOLR_OK             - Specified record is deleted.
 *  @retval LOLR_INV_HANDLE     - Bad LOL handle.
 *  @retval LOLR_REC_NOT_FOUND  - The specified record to be deleted is not in
 *                                the LOL object.
 *  @retval LOLR_INV_ARG        - 'ui2_lol_rec_id' is not a valid record id.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_del_rec (HANDLE_T  h_lol,
                            UINT16    ui2_lol_rec_id);

/*------------------------------------------------------------------*/
/*! @brief  This function updates a large object record to the LOL
 *          object. If the key field value (e.g., 'ui2_lol_rec_id' field
 *          in the 'pt_lol_rec' structure) of the input large object record
 *          matches an existing record in the LOL object, then the
 *          existing record is over-wrote with the new information,
 *          otherwise a new record is created in the LOL database.
 *
 *          If the 'b_must_exist' flag is TRUE, then there must be an
 *          existing record with the same key field value, else a status
 *          of 'LOLR_REC_NOT_FOUND' is returned to the caller.
 *          If 'b_must_exist' flag is FALSE, then a new large object record
 *          is created if no existing record matching the key field value
 *          is found in the LOL database.
 *
 *          Call to this function must be protected, e.g., the LOL
 *          database object needs to be locked before the call to this
 *          function and unlock after returning from call to this function.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  pt_lol_rec        - Pointer to large object record structure.
 *  @param  [in]  b_must_exist      - Boolean flag specifying if the large object
 *                                    record to be updated should exist in the
 *                                    LOL database.
 *  @return Return the error code
 *  @retval LOLR_OK             - Record is successfully added/updated.
 *  @retval LOLR_INV_HANDLE     - Bad LOL handle.
 *  @retval LOLR_OUT_OF_MEM     - Not enough memory to create a new LOL record.
 *  @retval LOLR_REC_NOT_FOUND  - The specified record is not found
 *                                ('b_must_exist' == TRUE)
 *  @retval LOLR_INV_ARG        - 'pt_lol_rec' is NULL or the pt_lol_rec
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_update_rec (HANDLE_T          h_lol,
                               const LOL_REC_T*  pt_lol_rec,
                               BOOL              b_must_exist);

/*------------------------------------------------------------------*/
/*! @brief  This API queries the range (FIRST, LAST, or NEXT) of
 *          valid large object record id values used in the LOL
 *          object.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  e_lol_qry_option  - Flag to specifies the record id value to
 *                                    be returned. The values are:
 *                                    LOL_FIRST_REC_ID,  LOL_LAST_REC_ID,
 *                                    LOL_NEXT_REC_ID.
 *  @param  [out] pui2_rec_id       - Contain the large object record id
 *  value.
 *  @return Return the error code
 *  @retval LOLR_OK                 - LOL record id return.
 *  @retval LOLR_INV_HANDLE         - Bad LOL handle.
 *  @retval LOLR_INV_ARG            - 'pui2_rec_id' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_qry_rec_id (HANDLE_T          h_lol,
                               LOL_REC_ID_QRY_T  e_lol_qry_option,
                               UINT16*           pui2_rec_id);

/*------------------------------------------------------------------*/
/*! @brief  This function locks the LOL object.   The function blocks
 *          until the lock is acquired.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @see    c_lol_unlock, c_lol_read_lock
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL is locked.
 *  @retval LOLR_INV_HANDLE     - Bad LOL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_lock (HANDLE_T  h_lol);

/*------------------------------------------------------------------*/
/*! @brief  This function unlocks the LOL database.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @see    c_lol_lock
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL database is unlocked.
 *  @retval LOLR_INV_HANDLE     - Bad LOL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_unlock (HANDLE_T  h_lol);

/*------------------------------------------------------------------*/
/*! @brief  This function acquires the read-lock on the LOL object.
 *          The function blocks until the lock is acquired.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @see    c_lol_read_unlock, c_lol_lock
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL is locked.
 *  @retval LOLR_INV_HANDLE     - Bad LOL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_read_lock (HANDLE_T  h_lol);

/*------------------------------------------------------------------*/
/*! @brief  This function releases the read-lock on the LOL database.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL database is unlocked.
 *  @retval LOLR_INV_HANDLE     - Bad LOL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_read_unlock (HANDLE_T  h_lol);

/*------------------------------------------------------------------*/
/*! @brief  This API gets a specific record stored in the LOL database
 *          object.    The search parameter is specified by the
 *          'ui2_lol_rec_id' value.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  ui2_lol_rec_id    - Specifies the large object record id.
 *  @param  [out] pt_lol_rec        - Pointer to a large object record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    large object record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the LOL database object is incremented each time when
 *          a modification takes place.
 *  @return Return the error code
 *  @retval LOLR_OK             - Data from the specified record is returned.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 *  @retval LOLR_REC_NOT_FOUND  - No record matching the search parameter
 *                                ('ui2_lol_rec_id')  is found.
 *  @retval LOLR_INV_ARG        - 'pui4_ver_id' or 'pt_lol_rec' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_get_rec (HANDLE_T    h_lol,
                            UINT16      ui2_lol_rec_id,
                            LOL_REC_T*  pt_lol_rec,
                            UINT32*     pui4_ver_id);

/*------------------------------------------------------------------*/
/*! @brief  This function returns the number of records for the
 *          specified LOL.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [out] pui2_num_recs     - Pointer to a variable for the number of
 *                                    records in the LOL.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the LOL database object.
 *  @return Return the error code
 *  @retval LOLR_OK             - Number of records in the specified LOL is
 *                                returned.
 *  @retval LOLR_INV_HANDLE     - Bad 'h_lol' handle.
 *  @retval LOLR_INV_ARG        - 'pui2_num_recs' or 'pui4_ver_id' is a NULL
 *                                pointer.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_get_num_rec (HANDLE_T  h_lol,
                                UINT16*   pui2_num_recs,
                                UINT32*   pui4_ver_id);

/*------------------------------------------------------------------*/
/*! @brief  This API gets a specific record stored in the LOL database
 *          object.    The search parameter is specified by the
 *          'ui4_data_tag' value.  If there are multiple records matching
 *          the search parameter, the caller can use ui2_idx to iterate over
 *          records with the positive match.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  ui4_data_tag      - Specifies the data tag.
 *  @param  [in]  ui2_idx           - Index for iteration.
 *  @param  [out] pt_lol_rec        - Pointer to a large object record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    large object record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the LOL database object is incremented each time when
 *          a modification takes place.
 *  @return Return the error code
 *  @retval LOLR_OK             - Data from the specified record is returned.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 *  @retval LOLR_REC_NOT_FOUND  - Specified record is not found.
 *  @retval LOLR_INV_ARG        - 'pui4_ver_id' or 'pt_lol_rec' is NULL.
 *  @retval LOLR_MODIFIED       - The database has been modified.  The
 *                                'pui4_ver_id' passed into the API and the
 *                                internal database version id are not the same.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_get_rec_by_data_tag (HANDLE_T    h_lol,
                                        UINT32      ui4_data_tag,
                                        UINT16      ui2_idx,
                                        LOL_REC_T*  pt_lol_rec,
                                        UINT32*     pui4_ver_id);

/*------------------------------------------------------------------*/
/*! @brief  This function returns the number of records matching the
 *          given data tag for the specified LOL.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  ui4_data_tag      - Specifies the data tag.
 *  @param  [out] pui2_num_recs     - Pointer to a variable for the number of
 *                                    records with matching data tag in the
 *                                    LOL.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the LOL database object.
 *  @return Return the error code
 *  @retval LOLR_OK             - Number of records in the specified LOL is
 *                                returned.
 *  @retval LOLR_INV_HANDLE     - Bad 'h_lol' handle.
 *  @retval LOLR_INV_ARG        - 'pui2_num_recs' or 'pui4_ver_id' is a NULL
 *                                pointer.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_get_num_rec_by_data_tag(HANDLE_T  h_lol,
                                           UINT32    ui4_data_tag,
                                           UINT16*   pui2_num_recs,
                                           UINT32*   pui4_ver_id);

/*------------------------------------------------------------------*/
/*! @brief  This API pre-sets the LOL_REC_T structure to a
 *          pre-defined invalid value (e.g., 0xFF).   The pre-defined invalid
 *          value can be used to detect changes in the LOL_REC_T structure for
 *          backward compatibility in the future.
 *
 *          For example, if a new field is added to the LOL record structure.
 *          At the runtime, if the new field in the LOL_REC_T structure passed
 *          into LOL library contain 0xFF, then we know the caller has not been
 *          re-compile with the new LOL module.
 *  @param  [out] pt_lol_rec        - Pointer to a LOL record structure.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL library is initialized successfully.
 *  @retval LOLR_INV_ARG        - 'pt_lol_rec' is a NULL pointer.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_rec_init (LOL_REC_T*  pt_lol_rec);

/*------------------------------------------------------------------*/
/*! @brief  This API loads a specified LOL object from file system
 *          into memory, and returns a handle to the newly created
 *          LOL object.
 *  @param  [in]  h_dir             - Handle to the parent directory of the file
 *                                    specified by the path 'ps_lol_path'.  If
 *                                    'ps_lol_path' is an absolute path, then
 *                                    this argument should be set to
 *                                    'FM_ROOT_HANDLE'.
 *  @param  [in]  ps_lol_path       - Specifies the path to the file where the
 *                                    LOL objects are stored in the file system.
 *  @param  [in]  ui2_lol_id        - Specifies the LOL id to load from the file
 *                                    system.  The limit for LOL ID is between 1
 *                                    and 65535.
 *  @param  [in]  ps_lol_name       - Specifies the name for the LOL object.  If
 *                                    null string is specified, then the default
 *                                    name stored in the file system is used to
 *                                    create the LOL object.
 *  @param  [in]  pv_tag            - Pointer to a private tag value provided by
 *                                    the caller.  This tag value is passed to
 *                                    the caller's notification function.
 *  @param  [in]  pf_nfy            - Notification function provided by the
 *                                    caller.  This function is called to notify
 *                                    the owner of this LOL handle when the LOL
 *                                    object has been modified by another
 *                                    client.  If NULL, then no notification
 *                                    function will be called.
 *  @param  [out] ph_lol            - On return, contain the handle to the LOL
 *                                    object created from file system.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL object is created.
 *  @retval LOLR_NOT_FOUND      - 'ui2_lol_id' is not found or 'ps_lol_path'
 *                                does not exist.
 *  @retval LOLR_OUT_OF_HANDLE  - Cannot get a handle.
 *  @retval LOLR_OUT_OF_MEM     - Not enough memory to create LOL object.
 *  @retval LOLR_FAIL           - The specified 'ps_lol_name' or 'ui2_lol_id'
 *                                value is not unique.
 *  @retval LOLR_INV_ARG        - 'ph_lol' or 'ps_lol_path' is NULL.
 *  @retval LOLR_AEE_OUT_OF_RESOURCES   - Can not allocate AEE resources.
 *  @retval LOLR_AEE_NO_RIGHTS  - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_fs_load (HANDLE_T       h_dir,
                            const CHAR*    ps_lol_path,
                            UINT16         ui2_lol_id,
                            const CHAR*    ps_lol_name,
                            VOID*          pv_tag,
                            x_lol_nfy_fct  pf_nfy,
                            HANDLE_T*      ph_lol);

/*------------------------------------------------------------------*/
/*! @brief  This API stores the specified LOL object to the file system.
 *  @param  [in]  h_dir             - Handle to the parent directory of the file
 *                                    specified by the path 'ps_lol_path'.  If
 *                                    'ps_lol_path' is an absolute path, then
 *                                    this argument should be set to
 *                                    'FM_ROOT_HANDLE'.
 *  @param  [in]  ps_lol_path       - Specifies the file path to the file where
 *                                    the LOL objects are stored in the file
 *                                    system.
 *  @param  [in]  ui2_lol_id        - Specifies the  ID of the LOL object to be
 *                                    stored to the file system.  The limit for
 *                                    LOL ID is between 1 and 65535.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL object is stored to the file system.
 *  @retval LOLR_NOT_FOUND      - The LOL object specified by the 'ui2_lol_id'
 *                                does not exist.
 *  @retval LOLR_INV_ARG        - 'ps_lol_path' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_fs_store (HANDLE_T     h_dir,
                             const CHAR*  ps_lol_path,
                             UINT16       ui2_lol_id);

/*------------------------------------------------------------------*/
/*! @brief  This API deletes a specified LOL object on the file system.
 *  @param  [in]  h_dir             - Handle to the parent directory of the file
 *                                    specified by the path 'ps_lol_path'.  If
 *                                    'ps_lol_path' is an absolute path, then
 *                                    this argument should be set to
 *                                    'FM_ROOT_HANDLE'.
 *  @param  [in]  ps_lol_path       - Specifies the file path to the file where
 *                                    the LOL objects are stored in the file
 *                                    system.
 *  @param  [in]  ui2_lol_id        - Specifies the ID of the LOL object to be
 *                                    deleted from the file system.  The limit
 *                                    for LOL ID is between 1 and 65535.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL object is deleted from the file system.
 *  @retval LOLR_NOT_FOUND      - 'ui2_lol_id' is not found or 'ps_lol_path'
 *                                does not exist.
 *  @retval LOLR_INV_ARG        - 'ps_lol_path' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_fs_del (HANDLE_T     h_dir,
                           const CHAR*  ps_lol_path,
                           UINT16       ui2_lol_id);

/*------------------------------------------------------------------*/
/*! @brief  This API queries the LOL objects stored in file system.
 *  @param  [in]  h_dir             - Handle to the parent directory of the file
 *                                    specified by the path 'ps_lol_path'.  If
 *                                    'ps_lol_path' is an absolute path, then
 *                                    this argument should be set to
 *                                    'FM_ROOT_HANDLE'.
 *  @param  [in]  ps_lol_path       - Specifies the file path to the file where
 *                                    the LOL objects are stored in the file
 *                                    system..
 *  @param  [in]  ui2_idx           - Index value to get the next LOL object. 0
 *                                    means the first LOL, 1 is the second LOL,
 *                                    etc.
 *  @param  [out] pui2_lol_id       - Pointer to a UINT16 variable. On return,
 *                                    it contains LOL ID.
 *  @param  [out] ps_lol_name       - Pointer to a string buffer (minimum 17
 *                                    bytes) .  On return, it contains the
 *                                    default LOL name stored on the file
 *                                    system.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL object found.
 *  @retval LOLR_NOT_FOUND      - No LOL object found.
 *  @retval LOLR_INV_ARG        - 'ps_lol_name' or 'pui2_lol_id' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_fs_qry (HANDLE_T    h_dir,
                          const CHAR*  ps_lol_path,
                          UINT16       ui2_idx,
                          UINT16*      pui2_lol_id,
                          CHAR*        ps_lol_name);

/*------------------------------------------------------------------*/
/*! @brief  This API sync a specified LOL handle with LOL records
 *          from persistent file system.  The existing LOL records
 *          are replaced with new records read from file.
 *  @param  [in]  h_lol             - Specify the handle to the LOL object.
 *  @param  [in]  h_dir             - The handle to the directory.  The
 *                                    'ps_lol_path' will be relative to the
 *                                    specified 'h_dir'.
 *  @param  [in]  ps_lol_path       - Specifies the directory path of the LOL
 *                                    object in the file system. See File Path
 *                                    Specification, 10.1, for the types of file
 *                                    path that can be specified.
 *  @param  [in]  ui2_lol_id        - Specifies the LOL id to load from the file
 *                                    system.  The limit for LOL ID is between 1
 *                                    and 65535.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL records are load from the persistent file
 *                                into the memory of LOL object.
 *  @retval LOLR_NOT_FOUND      - 'ui2_lol_id' is not found or 'ps_lol_path'
 *                                does not exist.
 *  @retval LOLR_FAIL           - internal error
 *  @retval LOLR_INV_ARG        - 'ps_lol_path' is NULL, or 'h_lol' is
 *                                NULL_HANDLE, or ui2_lol_id is 0.
 *  @retval LOLR_INV_FILE_PATH  - Specified file path is not a directory or a
 *                                RAW character file.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_fs_sync (HANDLE_T    h_lol,
                           HANDLE_T     h_dir,
                           const CHAR*  ps_lol_path,
                           UINT16       ui2_lol_id);

/*------------------------------------------------------------------*/
/*! @brief  This API specifies a entry position in LOL records,
 *          which will read when API c_lol_read_cursor() is called.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  e_pos             - Position of the LOL record to read.
 *  @see    c_lol_read_cursor
 *  @return Return the error code
 *  @retval LOLR_OK             - Data from the specified record is returned.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 *  @retval LOLR_INV_ARG        - 'e_pos' is invalid.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_set_cursor ( HANDLE_T            h_lol,
                                LOL_ITERATE_T       e_pos);

/*------------------------------------------------------------------*/
/*! @brief  This API read the content of a specific record
 *          stored in the LOL database.  The specific record is read
 *          is the record currently pointed by the cursor.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [out] pt_lol_rec        - Pointer to a LOL record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    LOL record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the LOL database object is incremented each time when
 *          a modification takes place.
 *  @see    c_lol_set_cursor
 *  @return Return the error code
 *  @retval LOLR_OK             - Data from the specified record is returned.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 *  @retval LOLR_INV_ARG        - 'pui4_ver_id' or 'pt_lol_rec' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_read_cursor ( HANDLE_T            h_lol,
                                 LOL_REC_T*          pt_lol_rec,
                                 UINT32*             pui4_ver_id);

/*------------------------------------------------------------------*/
/*! @brief  This API applies the sort operation (using the
 *          per-handle compare fucntion, or the global compare
 *          function, or default compare function, to the LOL
 *          records.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [out] pui4_ver_id       - Contains the version id of the LOL
 *                                    database object.
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL record are sorted and internal sort list
 *                                is updated.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_sort_rec ( HANDLE_T			  h_lol,
                              UINT32*             pui4_ver_id );

/*------------------------------------------------------------------*/
/*! @brief  This API initializes the memory dump structure, which
 *          is used for c_lol_dump_to_mem.
 *  @param  [out] pt_mem_dump       - Pointer to the memory dump structure.
 *  @see    c_lol_dump_to_mem
 *  @return Return the error code
 *  @retval LOLR_OK             - Success.
 *  @retval LOLR_INV_ARG        - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_init_mem_dump     (LOL_MEM_DUMP_T*        pt_mem_dump);

/*------------------------------------------------------------------*/
/*! @brief  This API deinitializes the memory dump structure.
 *  @param  [in]  pt_mem_dump       - Pointer to the memory dump structure.
 *  @return Return the error code
 *  @retval LOLR_OK             - Success.
 *  @retval LOLR_INV_ARG        - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_free_mem_dump     (LOL_MEM_DUMP_T*        pt_mem_dump);

/*------------------------------------------------------------------*/
/*! @brief  This API dumps the specified LOL database into the specified
 *          structure, which could be later used for c_lol_load_from_mem.
 *          The memory dump structure should be initialized before dumping.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [out] pt_mem_dump       - Pointer to the memory dump structure.
 *  @see    c_lol_load_from_mem
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL database successfully dumped.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 *  @retval LOLR_INV_ARG        - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_dump_to_mem       (HANDLE_T               h_lol,
                                      LOL_MEM_DUMP_T*        pt_mem_dump);

/*------------------------------------------------------------------*/
/*! @brief  This API loads the LOL database from the specified memory
 *          dump structure, whose data comes from a previous call to
 *          c_lol_load_from_mem.
 *  @param  [in]  h_lol             - Handle to the LOL object.
 *  @param  [in]  pt_mem_dump       - Pointer to the memory dump structure.
 *  @see    c_lol_dump_to_mem, c_lol_free_mem_dump
 *  @return Return the error code
 *  @retval LOLR_OK             - LOL database successfully loaded.
 *  @retval LOLR_INV_HANDLE     - Bad handle.
 *  @retval LOLR_INV_ARG        - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_lol_load_from_mem     (HANDLE_T               h_lol,
                                      LOL_MEM_DUMP_T*        pt_mem_dump);

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