/* 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_fm_mfw.h 
 *  $RCSfile: $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This header file contains Multi-File-Wrapper exported constants, macros,
 *         and types.
 */
/*----------------------------------------------------------------------------*/

#ifndef _U_FM_MFW_H_
#define _U_FM_MFW_H_

/*-----------------------------------------------------------------------------
                    include files
-----------------------------------------------------------------------------*/
#include "u_fm.h"


/*!
 * @defgroup    groupMW_FM_MFW Multi File Wrapper
 * @ingroup     groupMW_FM
 * @brief    This header file contains Multi-File-Wrapper exported constants, macros, and types.
 * %MFW is a wrapper of multi files, user can access it as a visual file.
 * 
 * @see groupMW_FM
 *
 * @{
 * */



/*-----------------------------------------------------------------------------
                    macros, defines, typedefs, enums
 ----------------------------------------------------------------------------*/
/*------------------------------------------------------------------*/
/*! @enum   FM_MFW_ASYNC_COND_T
 *  @brief  Async condition
 *  @code
 *  typedef enum _FM_MFW_ASYNC_COND_T
 *  {
 *      FM_MFW_ASYNC_COND_CREATE_FAIL,
 *      FM_MFW_ASYNC_COND_ANLS_FAIL,
 *      FM_MFW_ASYNC_COND_ABORT_FAIL,
 *      FM_MFW_ASYNC_COND_ABORT_OK,
 *      FM_MFW_ASYNC_COND_ANLS_OK,
 *      FM_MFW_ASYNC_COND_CREATE_OK,
 *      FM_MFW_ASYNC_COND_PRGS,  
 *      FM_MFW_ASYNC_COND_STATUS,
 *  } FM_MFW_ASYNC_COND_T;  
 *  @endcode
 *  @li@c  FM_MFW_ASYNC_COND_CREATE_FAIL                    - Failed to create MFW
 *  @li@c  FM_MFW_ASYNC_COND_ANLS_FAIL                       - Analyse the device failed
 *  @li@c  FM_MFW_ASYNC_COND_ABORT_FAIL                     - Failed to abort
 *  @li@c  FM_MFW_ASYNC_COND_ABORT_OK                        - Abort OK
 *  @li@c  FM_MFW_ASYNC_COND_ANLS_OK                         - Analysed OK
 *  @li@c  FM_MFW_ASYNC_COND_CREATE_OK                     - Created OK
 *  @li@c  FM_MFW_ASYNC_COND_PRGS                               - Notify progress 
 *  @li@c  FM_MFW_ASYNC_COND_STATUS                           - Notify status
 */
/*------------------------------------------------------------------*/
typedef enum _FM_MFW_ASYNC_COND_T
{
    FM_MFW_ASYNC_COND_CREATE_FAIL,
    FM_MFW_ASYNC_COND_ANLS_FAIL,
    FM_MFW_ASYNC_COND_ABORT_FAIL,
    FM_MFW_ASYNC_COND_ABORT_OK,
    FM_MFW_ASYNC_COND_ANLS_OK,
    FM_MFW_ASYNC_COND_CREATE_OK,
    FM_MFW_ASYNC_COND_PRGS,
    FM_MFW_ASYNC_COND_STATUS,
} FM_MFW_ASYNC_COND_T;  

/* (*x_fm_async_fct) (e_async_cond = FM_ASYNC_COND_READ_OK, ui4_data: (done bytes) ) */
/* (*x_fm_async_fct) (e_async_cond = FM_ASYNC_COND_WRITE_OK, ui4_data: (done bytes) ) */
/* (*x_fm_async_fct) (e_async_cond = FM_MFW_ASYNC_COND_FAIL, ui4_data: (N/A) ) */

/* (*x_fm_mfw_async_fct) (e_async_cond = FM_MFW_ASYNC_COND_ABORT_OK, ui4_data: (N/A) ) */
/* (*x_fm_mfw_async_fct) (e_async_cond = FM_MFW_ASYNC_COND_ANLS_OK, ui4_data: (FM_MFW_ANLS_RES_T *) ) */
/* (*x_fm_mfw_async_fct) (e_async_cond = FM_MFW_ASYNC_COND_CREATE_OK, ui4_data: (N/A) ) */
/* (*x_fm_mfw_async_fct) (e_async_cond = FM_MFW_ASYNC_COND_ABORT_FAIL, ui4_data: FM_MFW_NFY_FAIL_* ) */
/* (*x_fm_mfw_async_fct) (e_async_cond = FM_MFW_ASYNC_COND_CREATE_FAIL, ui4_data: FM_MFW_NFY_FAIL_* ) */
/* (*x_fm_mfw_async_fct) (e_async_cond = FM_MFW_ASYNC_COND_ANLS_FAIL, ui4_data: FM_MFW_NFY_FAIL_* ) */
#define FM_MFW_NFY_FAIL_CORE_ERROR                  ((UINT32) 1)   /**< Internal error or OSAI error */
#define FM_MFW_NFY_FAIL_DEVICE_ERROR                ((UINT32) 2)   /**< IO error */
#define FM_MFW_NFY_FAIL_NO_ENOUGH_SPACE             ((UINT32) 3)   /**< No enough free space in device */
#define FM_MFW_NFY_FAIL_NO_ENOUGH_CONTINS_SPACE     ((UINT32) 4)   /**< For FM_MFW_VF_POLICY_PHYSIC_CONTINS_FORCE, when there is no more continuous space */
#define FM_MFW_NFY_FAIL_ABORTED                     ((UINT32) 5)   /**< For FM_MFW_ASYNC_COND_ANLS_FAIL and FM_MFW_ASYNC_COND_CREATE_FAIL, when the analyse request is aborted */
#define FM_MFW_NFY_FAIL_ALREADY_DONE                ((UINT32) 6)   /**< For FM_MFW_ASYNC_COND_ABORT_FAIL, when the request is already done */
#define FM_MFW_NFY_FAIL_ALREADY_EXISTED             ((UINT32) 7)   /**< For FM_MFW_ASYNC_COND_ABORT_FAIL, when the request is already done */
#define FM_MFW_NFY_FAIL_UMOUNTED                    ((UINT32) 8)   /**< Internal error or OSAI error */
#define FM_MFW_NFY_FAIL_NOT_SUPPORTED               ((UINT32) 9)   /**<  Not supported now */

/* (*x_fm_mfw_async_fct) (e_nfy_code = FM_MFW_NFY_CODE_STATUS, ui4_data: FM_MFW_NFY_STATUS_* ) */
#define FM_MFW_NFY_STATUS_NO_ENOUGH_CONTINS_SPACE   ((UINT32) 1)   /*  */    /**<  For FM_MFW_VF_POLICY_PHYSIC_CONTINS_PREFER, when there is no more continuous space, AP may do sth for this. */

/* (*x_fm_mfw_async_fct) (e_nfy_code = FM_MFW_ASYNC_COND_PRGS, ui4_data: (FM_MFW_PROGRESS_T *) ) */
/*------------------------------------------------------------------*/
/*! @struct FM_MFW_PRGS_T
 *  @brief Analyse or create progress info.
 *  @code
 *  typedef struct _FM_MFW_PRGS_T
 *  {
 *      UINT8               ui1_total_phases;
 *      UINT8               ui1_cur_phase;
 *      UINT32              ui4_prgs;
 *  } FM_MFW_PRGS_T;
 *  @endcode
 *  @li@c  ui1_total_phases                                  - Total phases
 *  @li@c  ui1_cur_phase                                     - Current phase
 *  @li@c  ui4_prgs                                             - Current progress 
 */
/*------------------------------------------------------------------*/
typedef struct _FM_MFW_PRGS_T
{
    UINT8               ui1_total_phases;
    UINT8               ui1_cur_phase;
    UINT32              ui4_prgs;
} FM_MFW_PRGS_T;


/*------------------------------------------------------------------*/
/*! @brief async callback to tell AP the result of the analysing or creating operation.
 */
/*------------------------------------------------------------------*/
typedef VOID (*x_fm_mfw_async_fct)(
    HANDLE_T            h_req,
    VOID                *pv_tag,
    FM_MFW_ASYNC_COND_T e_async_cond,
    UINT32              ui4_data);


/*------------------------------------------------------------------*/
/*! @enum   FM_MFW_VF_POLICY_T
 *  @brief  Policy applied when create visual files
 *  @code
 *  typedef enum _FM_MFW_VF_POLICY_T
 *  {
 *      FM_MFW_VF_POLICY_NO_CONSTRAINT,
 *      FM_MFW_VF_POLICY_PHYSIC_CONTINS_FORCE,
 *      FM_MFW_VF_POLICY_PHYSIC_CONTINS_PREFER    
 *  } FM_MFW_VF_POLICY_T;
 *  @endcode
 *  @li@c  FM_MFW_VF_POLICY_NO_CONSTRAINT                    -
 *  @li@c  FM_MFW_VF_POLICY_PHYSIC_CONTINS_FORCE             -
 *  @li@c  FM_MFW_VF_POLICY_PHYSIC_CONTINS_PREFER            -
 */
/*------------------------------------------------------------------*/
typedef enum _FM_MFW_VF_POLICY_T
{
    FM_MFW_VF_POLICY_NO_CONSTRAINT,
    FM_MFW_VF_POLICY_PHYSIC_CONTINS_FORCE,
    FM_MFW_VF_POLICY_PHYSIC_CONTINS_PREFER    
} FM_MFW_VF_POLICY_T;

/*------------------------------------------------------------------*/
/*! @enum   FM_MFW_VF_POLICY_T
 *  @brief  Meta file policy applied when create visual files
 *  @code
 *  typedef enum _FM_MFW_VF_META_POLICY_T
 *  {
 *      FM_MFW_VF_META_POLICY_VISIBLE_META_FILE,
 *      FM_MFW_VF_META_POLICY_INVISIBLE_META_FILE   
 *  } FM_MFW_VF_META_POLICY_T;
 *  @endcode
 *  @li@c  FM_MFW_VF_META_POLICY_VISIBLE_META_FILE                 - Visible meta file
 *  @li@c  FM_MFW_VF_META_POLICY_INVISIBLE_META_FILE             - Invisible meta file
 */
/*------------------------------------------------------------------*/
typedef enum _FM_MFW_VF_META_POLICY_T
{
    FM_MFW_VF_META_POLICY_VISIBLE_META_FILE,
    FM_MFW_VF_META_POLICY_INVISIBLE_META_FILE
} FM_MFW_VF_META_POLICY_T;

/*------------------------------------------------------------------*/
/*! @struct FM_MFW_ANLS_PARAM_T
 *  @brief  Analysing parameters
 *  @code
 *  typedef struct _FM_MFW_ANLS_PARAM_T
 *  {
 *      UINT8                   ui1_strct_ver;
 *      CHAR*                   s_mp_path;
 *      x_fm_mfw_async_fct      pf_nfy;
 *      VOID*                   pv_tag;
 *  } FM_MFW_ANLS_PARAM_T;
 *  @endcode
 *  @li@c  ui1_strct_ver                                  - Version
 *  @li@c  s_mp_path                                     - Mount point path
 *  @li@c  pf_nfy                                            - Callback function
 *  @li@c  pv_tag                                           - Tag
 */
/*------------------------------------------------------------------*/
typedef struct _FM_MFW_ANLS_PARAM_T
{
    UINT8                   ui1_strct_ver;
    CHAR*                   s_mp_path;
    x_fm_mfw_async_fct      pf_nfy;
    VOID*                   pv_tag;
} FM_MFW_ANLS_PARAM_T;


/*------------------------------------------------------------------*/
/*! @struct FM_MFW_ANLS_RESULT_T
 *  @brief  Analysing results
 *  @code
 *  typedef struct _FM_MFW_ANLS_RESULT_T
 *  {
 *      UINT64  ui8_continuous_size;
 *      UINT64  ui8_avail_size;
 *  } FM_MFW_ANLS_RESULT_T;
 *  @endcode
 *  @li@c  ui8_continuous_size  -   Size of all the continuous regions in device;
 *                                  Continuous region is a region whose size is not less than 32MB
 *  @li@c  ui8_avail_size       -   Available space in the device
 */
/*------------------------------------------------------------------*/
typedef struct _FM_MFW_ANLS_RESULT_T
{
    /* Size of all the continuous regions in device;
       Continuous region is a region whose size is not less than 32MB */
    UINT64  ui8_continuous_size;

    /* Available space in the device */
    UINT64  ui8_avail_size;
} FM_MFW_ANLS_RESULT_T;


/*------------------------------------------------------------------*/
/*! @struct FM_MFW_VF_CFG_T
 *  @brief  Creating configs
 *  @code
 *  typedef struct _FM_MFW_VF_CFG_T
 *  {
 *      UINT8                   ui1_strct_ver;
 *      FM_MFW_VF_POLICY_T      e_vf_policy;
 *      FM_MFW_VF_META_POLICY_T e_meta_policy;
 *      UINT64                  ui8_init_size;
 *      x_fm_mfw_async_fct      pf_nfy;
 *      VOID*                   pv_tag; 
 *      CHAR*                   s_dir;
 *      CHAR*                   s_meta_file;
 *      CHAR*                   s_fn_pattern;
 *  } FM_MFW_VF_CFG_T;  
 *  @endcode
 *  @li@c  ui1_strct_ver                                 - Version
 *  @li@c  e_vf_policy                                    - VF policy
 *  @li@c  e_meta_policy                               - Meta policy
 *  @li@c  ui8_init_size                                  - Init size
 *  @li@c  pf_nfy                                           - Callback function
 *  @li@c  pv_tag                                          - Tag
 *  @li@c  s_dir                                             - The path of the directory to gengrate the wrapper files.
 *  @li@c  s_meta_file                                   - s_meta_file is valid only when e_meta_policy equals to FM_MFW_VF_META_POLICY_VISIBLE_META_FILE 
 *                                                                    s_meta_file is file name only, should not contain any path.
 *  @li@c  s_fn_pattern                                 -  s_fn_pattern is used for generate the name of the files in the wrapper.
 *                                                                    s_fn_pattern should like "xxxxxx%xdxxx"(for example, "Timeshift_PRG1_%03d.ts"), otherwise the result is unknown.
 *                                                                    s_fn_pattern is file name only, should not contain any path.
 */
/*------------------------------------------------------------------*/
typedef struct _FM_MFW_VF_CFG_T
{
    UINT8                   ui1_strct_ver;

    FM_MFW_VF_POLICY_T      e_vf_policy;
    
    FM_MFW_VF_META_POLICY_T e_meta_policy;
    
    UINT64                  ui8_init_size;
    
    x_fm_mfw_async_fct      pf_nfy;
    
    VOID*                   pv_tag;

    /* The path of the directory to gengrate the wrapper files.  */
    CHAR*                   s_dir;
    
    /* 
           s_meta_file is valid only when e_meta_policy equals to FM_MFW_VF_META_POLICY_VISIBLE_META_FILE 
           s_meta_file is file name only, should not contain any path.
       */
    CHAR*                   s_meta_file;

    /* 
           s_fn_pattern is used for generate the name of the files in the wrapper.
           s_fn_pattern should like "xxxxxx%xdxxx"(for example, "Timeshift_PRG1_%03d.ts"), otherwise the result is unknown.
           s_fn_pattern is file name only, should not contain any path.
       */
    CHAR*                   s_fn_pattern;

} FM_MFW_VF_CFG_T;  


/*-----------------------------------------------------------------------------
                    data declarations
 ----------------------------------------------------------------------------*/


/*-----------------------------------------------------------------------------
                    functions declarations
 ----------------------------------------------------------------------------*/
/*! @}  */

#endif /* _U_FM_MFW_H */
