/* 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_flm.h 
 *  $File: //DTV/MP_BR/DTV_X_IDTV1501_002288_8_001_800_002/apollo/middleware/public/flm/c_flm.h $
 *  $Revision: #1 $
 *  $Date: 2015/11/10 $
 *  $Author: dtvbm11 $
 *  
 *  @par Description:
 *         This header file contains Favorite List Manager (FLM) specific
 *         definitions, which are exported.
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_FLM_H_
#define _C_FLM_H_
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_FLM
 *  @{
 */
/*----------------------------------------------------------------------------*/

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

#include "u_common.h"
#include "u_handle.h"
#include "u_sys_name.h"
#include "u_flm.h"

/*-------------------------------------------------------------------------
                    macros, defines, typedefs, enums
 ------------------------------------------------------------------------*/

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

/*------------------------------------------------------------------*/
/*! @brief  This function creates a new empty favorites list and returns a
 *          handle, if successful.
 *  @param  [in]  ps_name           - User name associated with this list.
 *  @param  [in]  pv_tag            - Pointer to tag that will be passed to the
 *                                    notify function when it is called.
 *  @param  [in]  pf_flm_notify     - Function to be called if favorites list
 *                                    changes.  If there is none, this can be
 *                                    NULL.
 *  @param  [out] ph_fav_handle     - Pointer to variable to hold handle to the
 *                                    created list, if successful
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_ARG        - s_name too long or NULL was passed for s_name
 *                                or ph_fav_handle.
 *  @retval FLMR_OUT_OF_MEM     - Not enough free memory to create list.
 *  @retval FLMR_OUT_OF_HANDLE  - Not enough free handles to create list.
 *  @retval FLMR_INV_NAME       - A list of the same name already exists.
 *  @retval FLMR_LIMIT_EXCEED   - Too many favorites lists.
 *  @retval FLMR_AEE_OUT_OF_RESOURCES   - Could not allocate the requested
 *                                        resources.
 *  @retval FLMR_AEE_NO_RIGHTS  - Not allowed to allocate the requested
 *                                resources.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_create
(
    CHAR*           ps_name,
    VOID*           pv_tag,
    pf_flm_nfy_func pf_flm_notify,
    HANDLE_T*       ph_fav_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function deletes the specified favorites list. . Any other
 *          handles that are connected to the same favorites list as the given
 *          handle will have their notification routine called with a condition
 *          of FLM_CLOSED and reason of FLM_UNKNOWN.
 *  @param  [in]  h_fav_handle      - Handle to favorite list to be deleted.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_delete
(
    HANDLE_T h_fav_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the number of the favorites lists.
 *  @param  [out] pui2_numlists     - Number of favorite lists.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_ARG        - pui2_numlists was NULL.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_get_num_lists
(
    UINT16* pui2_numlists
);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the name of the specified favorites list.
 *  @param  [in]  ui2_listnum       - List number of favorites list to retrieve
 *                                    name.
 *  @param  [out] pz_length         - Length of the name of the specified
 *  favorites list.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_REC_NOT_FOUND  - No favorites list by that name.
 *  @retval FLMR_INV_ARG        - Invalid ui4_listnum.
 *  @retval FLMR_MODIFIED       - Version of master list has changed since we
 *                                got the version number.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_get_name_len
(
    UINT16  ui2_listnum,
    SIZE_T* pz_length
);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the name of the specified favorites list. 
 *
 *          For the first call, The value passed via pui4_master_version should
 *          be the value FLM_NULL_VER_ID. c_flm_get_name will then pass back the
 *          current version of the master list. The current version should be
 *          passed on subsequent calls.  If the passed version and the internal
 *          version do not match, due to the master list being changed by
 *          another thread, the call to c_flm_get_name will return
 *          FLMR_MASTER_CHANGED to alert the caller that the master list has
 *          changed since the last call.
 *  @param  [in]  ui2_listnum       - List number of favorites list to retrieve
 *                                    name.
 *  @param  [out] ps_name           - Name of the specified favorites list.
 *  @param  [in,out] pui4_master_version - Specifies the version of the list
 *                                         (FLM_NULL_VER_ID can be used as a
 *                                         placeholder if the version is unknown
 *                                         or irrelevant to the caller), and
 *                                         returns the actual version of the
 *                                         list if FLM_NULL_VER_ID was used.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_REC_NOT_FOUND  - No favorites list by that name.
 *  @retval FLMR_INV_ARG        - Invalid ui4_listnum.
 *  @retval FLMR_MODIFIED       - Version of master list has changed since we
 *                                got the version number.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_get_name
(
    UINT16  ui2_listnum,
    CHAR*   ps_name,
    UINT32* pui4_master_version
);

/*------------------------------------------------------------------*/
/*! @brief  This function opens an existing favorites list and returns a handle,
 *          if successful.
 *  @param  [in]  ps_name           - User name associated with this list.
 *  @param  [in]  pf_flm_notify     - Function to be called if favorites list
 *                                    changes. If there is none, this can be
 *                                    NULL.
 *  @param  [in]  pv_tag            - Pointer to tag that will be passed to the
 *                                    notify function when it is called.
 *  @param  [out] ph_fav_handle     - Pointer to variable to hold handle to the
 *                                    opened list, if successful.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_LIST_NOT_FOUND - A list with s_name could not be found.
 *  @retval FLMR_INV_ARG        - s_name too long or NULL was passed for s_name
 *                                or ph_fav_handle.
 *  @retval FLMR_OUT_OF_MEM     - Not enough free memory to open list.
 *  @retval FLMR_OUT_OF_HANDLE  - Not enough free handles to open list.
 *  @retval FLMR_AEE_OUT_OF_RESOURCES   - Could not allocate the requested
 *                                        resources.
 *  @retval FLMR_AEE_NO_RIGHTS  - Not allowed to allocate the requested
 *                                resources.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_open
(
    CHAR*           ps_name,
    VOID*           pv_tag,
    pf_flm_nfy_func pf_flm_notify,
    HANDLE_T*       ph_fav_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function closes the specified favorites list. The favorites
 *          list still exists in the database, but the specified handle can no
 *          longer access it.
 *  @param  [in]  h_fav_handle      - Handle to favorite list to be closed.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.a
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_close
(
    HANDLE_T    h_fav_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the maximum number of active (in memory)
 *          favorites lists allowed in the system.
 *  @return Maximum number of active (in memory) favorites lists
 */
/*------------------------------------------------------------------*/
extern
UINT16 c_flm_get_max_lists(VOID);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the maximum size (in records) of an active (in
 *          memory) favorites list.
 *  @return Maximum size (in records) of an active (in memory) favorites list 
 */
/*------------------------------------------------------------------*/
extern
UINT16 c_flm_get_max_size(VOID);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the number of records in the specified favorites
 *          list.
 *
 *          For the first call, the value passed via pui4_master_version should
 *          be the value FLM_NULL_VER_ID. c_flm_get_num_recs will then pass back
 *          the current version of the master list. The current version should
 *          be passed on subsequent calls. If the passed version and the
 *          internal version do not match, due to the master list being changed
 *          by another thread, the call to c_flm_get_num_recs will return
 *          FLMR_MASTER_CHANGED to alert the caller that the master list has
 *          changed since the last call.
 *  @param  [in]  h_fav_handle      - Handle to favorites list in which to find
 *                                    the position of the entry.
 *  @param  [out] pui2_num_records  - Pointer to the variable that will hold the
 *                                    number of entries.
 *  @param  [in,out] pui4_fav_version   - Pointer to the variable that holds the
 *                                        version number of the specified
 *                                        favorites list.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 *  @retval FLMR_INV_ARG        - Invalid entries pointer or version pointer.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_get_num_recs
(
    HANDLE_T    h_fav_handle,
    UINT16*     pui2_num_records,
    UINT32*     pui4_fav_version
);

/*------------------------------------------------------------------*/
/*! @brief  This function locks the specified favorites list for writing. It
 *          will block until read/write operations by other clients are
 *          completed. The handle must be locked if used in c_flm_move_rec,
 *          c_flm_add_rec, c_flm_del_rec, c_flm_swap_rec. Any other handles that
 *          are connected to the same favorites list as the given handle will
 *          have their notification routine called with a condition of
 *          FLM_UPDATING and a reason of FLM_UNKNOWN.
 *  @param  [in]  h_fav_handle      - Handle to favorite list to be locked.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_lock
(
    HANDLE_T    h_fav_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function unlocks the specified favorites list. Any other
 *          handles that are connected to the same favorites list as the given
 *          handle will have their notification routine called with a condition
 *          of FLM_UPDATED with a reason made of a combination of
 *          FLM_RECORD_ADD, FLM_RECORD_DEL, or FLM_RECORD_MOD.
 *  @param  [in]  h_fav_handle      - Handle to favorite list to be unlocked.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_unlock
(
    HANDLE_T    h_fav_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function adds the specified entry to the specified favorites
 *          list at the specified position, at most. If the position is beyond
 *          the position of the last used entry, the actual position will be
 *          right after the last used entry.
 *
 *          The handle should have been locked with c_flm_lock() before this is
 *          called.
 *  @param  [in]  h_fav_handle      - Handle to favorites list to modify.
 *  @param  [in]  pt_record         - Pointer to table entry.
 *  @param  [in]  pui2_position     - Pointer to position in list to add channel
 *                                    to.
 *  @note   This function affects current position in list if addition was
 *          successful.
 *  @return Return the error code
 *  @retval FLMR_OK             - Record was added successfully.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 *  @retval FLMR_INV_ARG        - Invalid ui2_position.
 *  @retval FLMR_LIMIT_EXCEED   - No free position in list.
 *  @retval FLMR_REC_NOT_FOUND  - List is corrupted.
 *  @retval FLMR_OUT_OF_MEM     - Out of memory.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_add_rec
(
    HANDLE_T      h_fav_handle,
    FLM_REC_T*    pt_record,
    UINT16*       pui2_position
);

/*------------------------------------------------------------------*/
/*! @brief  This function deletes the entry at the specified position. The
 *          handle should have been locked with c_flm_lock() before this is
 *          called.
 *  @param  [in]  h_fav_handle      - Handle to favorites list to modify.
 *  @param  [in]  ui2_position      - Position in list to delete entry from.
 *  @return Return the error code
 *  @retval FLMR_OK             - Record deleted successfully.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 *  @retval FLMR_REC_NOT_FOUND  - No record found at the indicated position.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_del_rec
(
    HANDLE_T h_fav_handle,
    UINT16   ui2_position
);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the entry from the specified position of the
 *          specified favorites list.
 *
 *          For the first call, the value passed via pui4_master_version should
 *          be the value FLM_NULL_VER_ID. c_flm_get_rec will then pass back the
 *          current version of the master list. The current version should be
 *          passed on subsequent calls.  If the passed version and the internal
 *          version do not match, due to the master list being changed by
 *          another thread, the call to c_flm_get_rec will return
 *          FLMR_MASTER_CHANGED to alert the caller that the master list has
 *          changed since the last call.
 *  @param  [in]  h_fav_handle      - Handle to favorites list to retrieve from.
 *  @param  [in]  ui2_position      - The position in the list of the entry to
 *                                    get.
 *  @param  [out] pt_rec            - Entry in that position, if any.
 *  @param  [in,out]  pui4_version  - Pointer to the version number of the
 *                                    specified favorites list.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_REC_NOT_FOUND  - No record with that entry was found.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 *  @retval FLMR_INV_ARG        - NULL passed for pt_rec.
 *  @retval FLMR_MODIFIED       - Favorites list version is different from
 *                                expected.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_get_rec
(
    HANDLE_T      h_fav_handle,
    UINT16        ui2_position,
    FLM_REC_T*    pt_rec,
    UINT32*       pui4_version
);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the position in the specified favorites list of
 *          the specified entry.
 *
 *          For the first call, the value passed via pui4_master_version should
 *          be the value FLM_NULL_VER_ID. c_flm_get_position will then pass back
 *          the current version of the master list. The current version should
 *          be passed on subsequent calls. If the passed version and the
 *          internal version do not match, due to the master list being changed
 *          by another thread, the call to c_flm_get_position will return
 *          FLMR_MASTER_CHANGED to alert the caller that the master list has
 *          changed since the last call.
 *  @param  [in]  h_fav_handle      - Handle to favorites list in which to find
 *                                    the position of the entry.
 *  @param  [in]  pt_rec            - Pointer to the entry in the favorites list
 *                                    to find the position of.
 *  @param  [in]  ui2_record_index  - Index number to select from multiple
 *                                    matching records. 0 = 1st matching, 1 =
 *                                    2nd matching, etc.
 *  @param  [out] pui2_position     - Position in the list that the specified
 *                                    entry occupies.
 *  @param  [in,out] pui4_version   - Pointer to the version number of the
 *                                    specified favorites list.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 *  @retval FLMR_INV_ARG        - Invalid position pointer or entry pointer.
 *  @retval FLMR_REC_NOT_FOUND  - Record not found.
 *  @retval FLMR_MODIFIED       - Favorites list version is different from
 *                                expected.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_get_position
(
    HANDLE_T     h_fav_handle,
    UINT16*      pui2_position,
    FLM_REC_T*   pt_rec,
    UINT16       ui2_record_index,
    UINT32*      pui4_version
);

/*------------------------------------------------------------------*/
/*! @brief  This function swaps the records in the specified positions in the
 *          specified favorites list.
 *  @param  [in]  h_fav_handle      - Handle to favorites list to swap entries
 *                                    of.
 *  @param  [in]  ui2_from          - Position in the list of the entry to swap.
 *  @param  [in]  ui2_to            - New position in the list for the entry.
 *  @note   The handle should have been locked with c_flm_lock() before this is
 *          called.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 *  @retval FLMR_INV_ARG        - Invalid from or to positions.
 *  @retval FLMR_REC_NOT_FOUND  - Either record was did not exist.
 *  @retval FLMR_LIMIT_EXCEED   - No free position in list.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_swap_rec
(
    HANDLE_T h_fav_handle,
    UINT16   ui2_from,
    UINT16   ui2_to
);

/*------------------------------------------------------------------*/
/*! @brief  This function move the entry from one position in the specified
 *          favorites list to another position within that list. Any existing
 *          items at and below that position are pushed down one position
 *          (essentially like a c_flm_del_rec followed by a c_flm_add_rec).
 *  @param  [in]  h_fav_handle      - Handle to favorites list to move entry in.
 *  @param  [in]  ui2_from_position - Position in the list of the entry to move.
 *  @param  [in,out] pui2_to_position   - Position in the list that the entry is
 *                                        moved to (actual position on return).
 *  @note   The handle should have been locked with c_flm_lock() before this is
 *          called.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_REC_NOT_FOUND  - Record to move could not be found.
 *  @retval FLMR_INV_HANDLE     - Invalid handle.
 *  @retval FLMR_INV_ARG        - Invalid from or to positions.
 *  @retval FLMR_LIMIT_EXCEED   - No free position in list.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_move_rec
(
    HANDLE_T h_fav_handle,
    UINT16   ui2_from_position,
    UINT16*  pui2_to_position
);

/*------------------------------------------------------------------*/
/*! @brief  This function registers for notification if the master list changes
 *          and returns a handle, if successful.
 *  @param  [in]  pf_flm_notify         - Function to be called if master list
 *                                        changes. This should never be NULL for
 *                                        this call.
 *  @param  [in]  pv_tag                - Pointer to tag that will be passed to
 *                                        the notify function when it is called.
 *  @param  [out] ph_notify_handle      - Pointer to variable to hold handle, if
 *                                        successful.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_ARG        - ph_fav_handle was NULL.
 *  @retval FLMR_OUT_OF_MEM     - Out of memory.
 *  @retval FLMR_OUT_OF_HANDLE  - Out of handles.
 *  @retval FLMR_AEE_OUT_OF_RESOURCES   - Could not allocate the requested
 *                                        resources.
 *  @retval FLMR_AEE_NO_RIGHTS  - Not allowed to allocate the requested
 *                                resources.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_master_change_reg(
    VOID*           pv_tag,
    pf_flm_nfy_func pf_flm_notify,
    HANDLE_T*       ph_notify_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function loads the specified favorites list from persistent
 *          storage. If the specified list was loaded, a handle is returned back
 *          to the caller.
 *  @param  [in]  h_dir             - Handle for directory to load from.
 *  @param  [in]  ps_pathname       - Path name of file to load from.
 *  @param  [in]  ps_listname       - Name of favorites list.
 *  @param  [in]  pv_tag            - Pointer to variable to be passed to
 *                                    notification function.
 *  @param  [in]  pf_flm_notify     - Pointer to notification function.
 *  @param  [out] ph_handle         - Pointer to handle variable.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_ARG        - h_dir is not a valid handle.
 *  @retval FLMR_OUT_OF_MEM     - Out of memory.
 *  @retval FLMR_OUT_OF_HANDLE  - Out of handle.
 *  @retval FLMR_LIMIT_EXCEED   - Too many favorites lists in CDB.
 *  @retval FLMR_LIST_NOT_FOUND - Could not find pv_listname list.
 *  @retval FLMR_INV_FILE       - FIle is not FLM file.
 *  @retval FLMR_INV_FILE_PATH  - File path name is not valid.
 *  @retval FLMR_CANT_CREATE_LIST - Error trying to create list.
 *  @retval FLMR_EOF            - File manager returns EOF.
 *  @retval FLMR_DEV_ERR        - File manager device error.
 *  @retval FLMR_OS_ERR         - File manager core error.
 *  @retval FLMR_PERM_DENY      - Don't have permission to access file.
 *  @retval FLMR_REC_NOT_FOUND  - An existing record is deleted from
 *                                CDB but name wasn't in master list.
 *  @retval FLMR_AEE_OUT_OF_RESOURCES   - Could not allocate the requested
 *                                        resources.
 *  @retval FLMR_AEE_NO_RIGHTS  - Not allowed to allocate the requested
 *                                resources.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_fs_load(
    HANDLE_T        h_dir,
    CHAR*           ps_pathname,
    CHAR*           ps_listname,
    VOID*           pv_tag,
    pf_flm_nfy_func pf_flm_notify,
    HANDLE_T*       ph_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function saves the specified favorites list to persistent
 *          storage.
 *  @param  [in]  h_dir             - Handle of directory to store to.
 *  @param  [in]  ps_pathname       - Path name of file to store to.
 *  @param  [in]  h_fav_handle      - Handle of favorites list to save.
 *  @return Return the error code
 *  @retval FLMR_OK               - Operation successful.
 *  @retval FLMR_INV_ARG          - Invalid argument.
 *  @retval FLMR_INV_HANDLE       - Invalid handle.
 *  @retval FLMR_OUT_OF_MEM       - Out of memory.
 *  @retval FLMR_OUT_OF_HANDLE    - Out of handle.
 *  @retval FLMR_LIST_NOT_FOUND   - Could not find pv_listname list.
 *  @retval FLMR_INV_FILE_PATH    - File path name is not valid.
 *  @retval FLMR_CANT_CREATE_FILE - Cannot create file.
 *  @retval FLMR_CANT_OPEN_FILE   - Cannot open file.
 *  @retval FLMR_NO_WRITE_LOCK    - No write lock for the file.
 *  @retval FLMR_DEV_ERR          - File manager device error.
 *  @retval FLMR_OS_ERR           - File manager core error.
 *  @retval FLMR_PERM_DENY        - Don't have permission to access file.
 *  @retval FLMR_REC_NOT_FOUND    - An existing record is deleted from
 *                                  CDB but name wasn't in master list.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_fs_store(
    HANDLE_T h_dir,
    CHAR*    ps_pathname,
    HANDLE_T h_fav_handle
);

/*------------------------------------------------------------------*/
/*! @brief  This function finds the name of a list corresponding to the index.
 *          If ui2_index is 0, then it returns the first name found, 1 returns
 *          the second one, and so on. The name of the found list will be copied
 *          into the buffer provided by the caller (pointed to by ps_listname).
 *  @param  [in]  h_dir             - Handle of directory to store to.
 *  @param  [in]  ps_pathname       - Name of file to store to.
 *  @param  [in]  ui2_index         - Index of matching file to look for.
 *  @param  [out] ps_listname       - Pointer to buffer to hold list name.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_ARG        - Invalid argument.
 *  @retval FLMR_OUT_OF_MEM     - Out of memory.
 *  @retval FLMR_OUT_OF_HANDLE  - Out of handle.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_fs_qry(
    HANDLE_T h_dir,
    CHAR*    ps_pathname,
    UINT16   ui2_index,
    CHAR*    ps_listname
);

/*------------------------------------------------------------------*/
/*! @brief  This function deletes the specified favorites list from persistent
 *          storage.
 *  @param  [in]  h_dir             - Handle of directory to delete from.
 *  @param  [in]  ps_pathname       - Path name of file to delete from.
 *  @param  [in]  ps_listname       - Name of favorites list to delete.
 *  @return Return the error code
 *  @retval FLMR_OK             - Operation successful.
 *  @retval FLMR_INV_ARG        - Invalid argument.
 *  @retval FLMR_OUT_OF_MEM     - Out of memory.
 *  @retval FLMR_OUT_OF_HANDLE  - Out of handle.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_flm_fs_del(
    HANDLE_T h_dir,
    CHAR*    ps_pathname,
    CHAR*    ps_listname
);

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

