/* 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_cl.h 
 *  $RCSfile: $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This file exports all compression library API and constant for 
 *         other module using.
 */
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_CL
 *  @{ 
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_CL_H_
#define _C_CL_H_

/*-----------------------------------------------------------------------------
                    include files
 ----------------------------------------------------------------------------*/
#include "u_handle.h"
#include "u_cl.h"
/*-----------------------------------------------------------------------------
                    macros, defines, typedefs, enums
 ----------------------------------------------------------------------------*/

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

/*------------------------------------------------------------------*/
/*! @brief   c_cl_nfy_fct
 *              The callback function used in x_cl_open_eng, x_cl_open_archive, 
 *              x_open_entry_by_name and x_cl_open_entry_by_index.
 *  @param [in] h_handle   The handle will be destoried. 
 *  @param [in] pv_nfy_tag  The client data specified by the client.
 *  @param [in] e_event      Usually is CL_NFY_EVENT_TYPE_T. 
 */
/*------------------------------------------------------------------*/
typedef VOID (*c_cl_nfy_fct) (
              HANDLE_T              h_handle,   /* (I) The handle will be destoried */
              VOID*                 pv_nfy_tag, /* (I)The client data specified by the client */
              CL_NFY_EVENT_TYPE_T   e_event     /* (I)usually is CL_NFY_EVENT_TYPE_T */
              );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_open_eng
 *              Open an engine for compression/decompression operation.
 *  @param [in] ps_name  Identifies sixteen characters engine name, and the character is case sensitive.
 *  @param [in] pf_nfy     Specify the notify callback function. 
 *  @param [in] pv_tag    The argument prepared by the user, and it will send back to user in (*x_cl_nfy_fct). 
 *  @param [out] ph_engine  The handle of the engine which want to be opened. 
 *  @return Return the error code.
 *  @retval CLR_OK                           The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG                   The argument ps_name or ph_engine is NULL.
 *  @retval CLR_ENG_NOT_FOUND        Cannot find the engine, which you want to open it.
 *  @retval CLR_OUT_OF_MEMORY       There is insufficient memory available to allocate structure.
 *  @retval CLR_OUT_OF_HANDLE         No more handles are available.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_open_eng (
             const CHAR*    ps_name,  /* (I)identifies sixteen characters engine name, and the character is case sensitive.*/
             c_cl_nfy_fct   pf_nfy,   /* (I)specify the notify callback function. */
             VOID*          pv_tag,   /* (I)the argument prepared by the user, and it will send back to user in (*x_cl_nfy_fct). */
             HANDLE_T*      ph_engine /* (O)The handle of the engine which want to be opened. */ 
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_close
 *              Close the entry, archive or engine after no more using. 
 *  @param [in] h_handle  The handle of a object which you already opened. 
 *  @return Return the error code.
 *  @retval  CLR_OK                The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG            The argument h_handle is a NULL_HANDLE.
 *  @retval CLR_INV_HANDLE        The handle is not valid any more. 
 *  @retval CLR_FCT_NOT_SUPPORT    The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_close (
             HANDLE_T           h_handle /* (I)the handle of a object which you already opened. */
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_get_compress_len
 *              This routine gets the length of compressed buffer after actually performs data compression from source buffer.
 *  @param [in] h_engine          Identifies the handle of the engine which performs compression operation. 
 *  @param [in] pv_src_buf        Point to the source buffer, and data in this buffer will be compressed. 
 *  @param [in] z_src_len         Specify the length of the source buffer. 
 *  @param [in] ui4_param_type    Specify type of compression paramters, set CL_NULL_PARAM_TYPE is using default.
 *  @param [in] pv_param          Specify compression paramters, set NULL is using default.
 *  @param [out] pz_dest_len Contains the compressed length after source  buffer is compressed.
 *  @return Return the error code.
 *  @retval CLR_OK                 The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG            The argument pv_src_buf or pz_dest_len contains a NULL pointer.
 *  @retval CLR_INV_HANDLE         The handle is not valid any more.
 *  @retval CLR_OUT_OF_MEMORY      The system runs out of memory.
 *  @retval CLR_COMPRESS_ERROR     The routine occurred error during compression algorithm process, such as other third-party error code or the symbol not found in codebook.
 *  @retval CLR_FCT_NOT_SUPPORT    The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_get_compress_len (
             HANDLE_T               h_engine,      /* (I)identifies the handle of the engine which performs compression operation */
             const VOID*            pv_src_buf,    /* (I)point to the source buffer, and data in this buffer will be compressed. */ 
             SIZE_T                 z_src_len,     /* (I)specify the length of the source buffer. */
             UINT32                 ui4_param_type,/* (I)specify type of compression paramters, set CL_NULL_PARAM_TYPE is using default */  
             VOID*                  pv_param,      /* (I)specify compression paramters, set NULL is using default */
             SIZE_T*                pz_dest_len    /* (O)contains the compressed length after source  buffer is compressed. */
             );

/*------------------------------------------------------------------*/
/*! @brief   c_cl_compress
 *               This routine compresses data from source buffer to destination buffer.
 *  @param [in] h_engine            Identifies the handle of the engine, which performs compression operation.
 *  @param [in] pv_src_buf          Point to the source buffer, which contains source data waiting for compression.
 *  @param [in] z_src_len           Specify the length of the source buffer.
 *  @param [in] ui4_param_type      Specify type of compression paramters, set CL_NULL_PARAM_TYPE is using default.
 *  @param [in] pv_param            Specify compression paramters, set NULL is using default.
 *  @param [out] pv_dest_buf     Point to the destination buffer.
 *  @param [in][out] pz_dest_len     Specify the length of the destination buffer./Specify the really compression length of destination buffer.
 *  @return Return the error code.
 *  @retval CLR_OK                     The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG                The argument pv_src_buf, pv_dest_buf or pz_dest_len contains a NULL pointer.
 *  @retval CLR_INV_HANDLE             The handle is not valid any more.
 *  @retval CLR_OUT_OF_MEMORY          The system runs out of memory.
 *  @retval CLR_COMPRESS_ERROR         The routine occurred error during compression algorithm process, such as other third-party error code or the symbol not found in codebook.
 *  @retval CLR_FCT_NOT_SUPPORT        The requested function was not supported. 
 *  @retval CLR_INSUFFICIENT_BUFFER    The destination buffer is insufficient for data compression of source buffer.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_compress (
             HANDLE_T               h_engine,      /* (I)identifies the handle of the engine, which performs compression operation */
             const VOID*            pv_src_buf,    /* (I)point to the source buffer, which contains source data waiting for compression. */
             SIZE_T                 z_src_len,     /* (I)specify the length of the source buffer. */
             UINT32                 ui4_param_type,/* (I)specify type of compression paramters, set CL_NULL_PARAM_TYPE is using default */  
             VOID*                  pv_param,      /* (I)specify compression paramters, set NULL is using default */
             VOID*                  pv_dest_buf,   /* (O)point to the destination buffer. */ 
             SIZE_T*                pz_dest_len    /* (I/O)specify the length of the destination buffer./specify the really compression length of destination buffer. */
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_get_decompress_len
 *             Get the length of the decompressed buffer after really decompress data from source buffer.
 *  @param [in] h_engine            Identifies the handle of the engine which performs compression operation 
 *  @param [in] pv_src_buf          Point to the source buffer, which contains source data waiting for decompression. 
 *  @param [in] z_src_len           Specify the length of the source buffer.
 *  @param [in] ui4_param_type      Specify type of decompression paramters, set CL_NULL_PARAM_TYPE is using default.
 *  @param [in] pv_param            Specify decompression paramters, set NULL is using default.
 *  @param [in][out] pz_dest_len     Contains the compressed length after source  buffer is compressed.
 *  @return Return the error code.
 *  @retval CLR_OK                     The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG                The argument pv_src_buf or pz_dest_len contains a NULL pointer.
 *  @retval CLR_INV_HANDLE             The handle is not valid any more.
 *  @retval CLR_OUT_OF_MEMORY          The system runs out of memory.
 *  @retval CLR_FCT_NOT_SUPPORT        The requested function was not supported.
 *  @retval CLR_DECOMPRESS_ERROR       The routine occurred error during decompression algorithm process, such as the bit stream is damage.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_get_decompress_len (
             HANDLE_T                 h_engine,      /* (I)identifies the handle of the engine which performs compression operation */
             const VOID*              pv_src_buf,    /* (I)point to the source buffer, which contains source data waiting for decompression. */
             SIZE_T                   z_src_len,     /* (I)specify the length of the source buffer. */
             UINT32                   ui4_param_type,/* (I)specify type of decompression paramters, set CL_NULL_PARAM_TYPE is using default */  
             VOID*                    pv_param,      /* (I)specify decompression paramters, set NULL is using default */
             SIZE_T*                  pz_dest_len    /* (O)contains the total compressed length after source buffer is compressed. */
             );

/*------------------------------------------------------------------*/
/*! @brief   c_cl_decompress
 *              Decompress data from source buffer to destination buffer.
 *  @param [in] h_engine            Identifies the handle of the engine which performs compression operation. 
 *  @param [in] pv_src_buf          Point to the source buffer. 
 *  @param [in] z_src_len           Specify the length of the source buffer. 
 *  @param [in] z_skip_len          Indicate the number of bytes to skip from the beginning of decompression output.
 *  @param [in] ui4_param_type      Specify type of decompression paramters, set CL_NULL_PARAM_TYPE is using default.
 *  @param [in] pv_param            Specify decompression paramters, set NULL is using default.
 *  @param [out] pv_dest_buf     Point to the destination buffer. 
 *  @param [in][out] pz_dest_len     Specify the length of destination buffer./Specify the really decompression length of destination buffer.
 *  @param [in][out] ph_prev_state  Set NULL if one shot;specify previous decompress state./ Next time decompress state.
 *  @return Return the error code.
 *  @retval CLR_OK                   The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG              The argument pv_src_buf, pv_dest_buf or pz_dest_len contains a NULL pointer.
 *  @retval CLR_INV_HANDLE           The handle is not valid any more.
 *  @retval CLR_OUT_OF_MEMORY        The system runs out of memory.
 *  @retval  CLR_FCT_NOT_SUPPORT      The requested function was not supported.
 *  @retval CLR_DECOMPRESS_ERROR     The routine occurred error during decompression algorithm process, such as the bit stream is damage.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_decompress (
             HANDLE_T                 h_engine,      /* (I)identifies the handle of the engine which performs compression operation */
             const VOID*              pv_src_buf,    /* (I)point to the source buffer. */
             SIZE_T                   z_src_len,     /* (I)specify the length of the source buffer. */ 
             SIZE_T                   z_skip_len,    /* (I)indicate the number of bytes to skip from the beginning of decompression output. */
             UINT32                   ui4_param_type,/* (I)specify type of decompression paramters, set CL_NULL_PARAM_TYPE is using default */  
             VOID*                    pv_param,      /* (I)specify decompression paramters, set NULL is using default */
             VOID*                    pv_dest_buf,   /* (O)point to the destination buffer. */
             SIZE_T*                  pz_dest_len,   /* (I/O)specify the length of the destination buffer./specify the really decompression length of destination buffer. */
             HANDLE_T*                ph_prev_state  /* (I/O)set NULL if one shot;specify previous decompress state/ next time decompress state */ 
             );
extern INT32 c_cl_decompress_ex(
             HANDLE_T                 h_engine,      /* (I)identifies the handle of the engine which performs compression operation */
             const VOID*              pv_src_buf,    /* (I)point to the source buffer. */
             SIZE_T                   z_src_len,     /* (I)specify the length of the source buffer. */ 
             SIZE_T                   z_skip_len,    /* (I)indicate the number of bytes to skip from the beginning of decompression output. */
             UINT32                   ui4_param_type,/* (I)specify type of decompression paramters, set CL_NULL_PARAM_TYPE is using default */  
             VOID*                    pv_param,      /* (I)specify decompression paramters, set NULL is using default */
             VOID*                    pv_dest_buf,   /* (O)point to the destination buffer. */
             SIZE_T*                  pz_dest_len,   /* (I/O)specify the length of the destination buffer./specify the really decompression length of destination buffer. */
             HANDLE_T*                ph_prev_state  /* (I/O)set NULL if one shot;specify previous decompress state/ next time decompress state */ 
             );

/*------------------------------------------------------------------*/
/*! @brief   c_cl_open_archive
 *               This routine creates and opens an archive for later entry operation. 
 *  @param [in] h_engine    Specified the handle of an engine.
 *  @param [in] ps_name     Specified the path name string of the archive. 
 *  @param [in] ui1_mode    Specified the access permit mode, and only support CL_READ_MODE.
 *  @param [in] pf_nfy      Specified the notify callback function. When ph_archive is not valid any more, the callback function pf_nfy will be called. 
 *  @param [in] pv_tag      The argument prepared by the user, and it will send back to user in (*x_cl_nfy_fct). 
 *  @param [out] ph_archive  Retrieve the archive handle.
 *  @return Return the error code.
 *  @retval CLR_OK                             The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG                     The argument ps_path or ppv_harchive contains a NULL pointer or ui1_mode is outside of definition.
 *  @retval CLR_INV_HANDLE                The handle is invalid.
 *  @retval CLR_OUT_OF_MEMORY         The system runs out of memory.
 *  @retval CLR_BAD_ARCHIVE               The archive is corrupted.
 *  @retval CLR_OUT_OF_HANDLE           No more handles are available.
 *  @retval CLR_FCT_NOT_SUPPORT        The requested function was not supported.
 *  @retval CLR_FILE_OR_DIR_MISSING    The input arguments of the file or directory name are invalid.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_open_archive (
             HANDLE_T       h_engine,  /* (I)specified the handle of an engine. */
             const CHAR*    ps_name,   /* (I)specified the path name string of the archive. */
             UINT8          ui1_mode,  /* (I)specified the access permit mode, and only support CL_READ_MODE. */
             c_cl_nfy_fct   pf_nfy,    /* (I)specify the notify callback function. When ph_archive is not valid any more, the callback function pf_nfy will be called. */
             VOID*          pv_tag,    /* (I)the argument prepared by the user, and it will send back to user in (*x_cl_nfy_fct). */
             HANDLE_T*      ph_archive /* (O)retrieve the archive handle. */ 
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_open_entry_by_name
 *              This routine creates or opens an entry, which has the path name string ps_name in the archive.
 *  @param [in] h_archive   The handle of the archive. 
 *  @param [in] ps_name     Specified the path name string of the entry which will be opened. 
 *  @param [in] pf_nfy      Specified the notify callback function. When ph_entry is not valid any more, the callback function pf_nfy will be called. 
 *  @param [in] pv_tag      The argument prepared by the user, and it will send back to user in (*x_cl_nfy_fct). 
 *  @param [out] ph_entry    Retrieve the handle of the entry.
 *  @return Return the error code.
 *  @retval CLR_OK                        The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG                    The argument pv_harchive, ps_name and ppv_hentry contain a NULL pointer.
 *  @retval CLR_OUT_OF_MEMORY            The system runs out of memory.
 *  @retval CLR_INV_HANDLE                The handle is not valid any more.
 *  @retval CLR_BAD_ARCHIVE                The archive is corrupted.
 *  @retval CLR_FILE_OR_DIR_MISSING        The input arguments of the file or directory name are invalid.
 *  @retval CLR_OUT_OF_HANDLE             No more handles are available.
 *  @retval CLR_FCT_NOT_SUPPORT            The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_open_entry_by_name (
             HANDLE_T       h_archive, /* (I)the handle of the archive. */
             const CHAR*    ps_name,   /* (I)specified the path name string of the entry which will be opened. */
             c_cl_nfy_fct   pf_nfy,    /* (I)specify the notify callback function. When ph_entry is not valid any more, the callback function pf_nfy will be called. */
             VOID*          pv_tag,    /* (I)the argument prepared by the user, and it will send back to user in (*x_cl_nfy_fct). */
             HANDLE_T*      ph_entry   /* (O)retrieve the handle of the entry. */
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_open_entry_by_index
 *              This routine opens an entry in the archive by index of entry numbers.
 *  @param [in] h_archive       The handle of the archive. 
 *  @param [in] ui4_entry_index Specified the index of the entry which will be opened, and it is 0 base.
 *  @param [in] pf_nfy          Specified the notify callback function. When ph_entry is not valid any more, the callback function pf_nfy will be called.
 *  @param [in] pv_tag          The argument prepared by the user, and it will send back to user in (*x_cl_nfy_fct).
 *  @param [out] ph_entry    Retrieve the handle of the entry. 
 *  @return Return the error code.
 *  @retval CLR_OK                The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG            The argument pv_harchive and ppv_hentry contain a NULL pointer or ui4_entry_index is out of entry number range.
 *  @retval CLR_OUT_OF_MEMORY    The system runs out of memory.
 *  @retval CLR_BAD_ARCHIVE        The archive is corrupted.
 *  @retval CLR_INV_HANDLE        The handle is not valid any more.
 *  @retval CLR_OUT_OF_HANDLE     No more handles are available.
 *  @retval CLR_FCT_NOT_SUPPORT    The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_open_entry_by_index (
             HANDLE_T       h_archive,       /* (I)the handle of the archive. */
             UINT32         ui4_entry_index, /* (I)specified the index of the entry which will be opened, and it is 0 base. */
             c_cl_nfy_fct   pf_nfy,          /* (I)specify the notify callback function. When ph_entry is not valid any more, the callback function pf_nfy will be called. */
             VOID*          pv_tag,          /* (I)the argument prepared by the user, and it will send back to user in (*x_cl_nfy_fct). */
             HANDLE_T*      ph_entry         /* (O)retrieve the handle of the entry. */
             );

/*------------------------------------------------------------------*/
/*! @brief   c_cl_decompress_entry
 *              This Routine will read and decompress data from the current entry file to the destination buffer, after open an entry in the archive.
 *  @param [in] h_entry         The handle of the entry.
 *  @param [in] z_skip_len      Indicate the number of Bytes which shall be skipped before data shall be actually written to the destination buffer.
 *  @param [out] pv_dest      The destination buffer that contains reading data.
 *  @param [in][out] pz_dest_len  Specified the really decompression length of destination buffer.
 *  @return Return the error code. 
 *  @retval CLR_OK                The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG            The argument pv_harchive and ppv_hentry contain a NULL pointer or ui4_entry_index is out of entry number range.
 *  @retval CLR_OUT_OF_MEMORY    The system runs out of memory.
 *  @retval CLR_BAD_ARCHIVE        The archive is corrupted.
 *  @retval CLR_INV_HANDLE        The handle is not valid any more.
 *  @retval CLR_OUT_OF_HANDLE     No more handles are available.
 *  @retval CLR_FCT_NOT_SUPPORT    The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_decompress_entry (
             HANDLE_T       h_entry,    /* (I)the handle of the entry. */
             SIZE_T         z_skip_len, /* (I)indicate the number of Bytes which shall be skipped before data shall be actually written to the destination buffer. */
             VOID*          pv_dest,    /* (O)the destination buffer that contains reading data. */
             SIZE_T*        pz_dest_len /* (I/O)specified the length of  the destination buffer./specify the really decompression length of destination buffer. */
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_get_decompress_entry_len
 *             This Routine will get the length of the current entry file except z_skip_len.
 *  @param [in] h_entry       The handle of the entry.
 *  @param [out] pz_dest_len    Specified the actual length, which is needed to decompress the entry data.
 *  @return Return the error code.
 *  @retval CLR_OK                The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG            The argument pz_dest_len contain a NULL pointer.
 *  @retval CLR_INV_HANDLE        The handle is not valid any more.
 *  @retval CLR_FCT_NOT_SUPPORT    The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_get_decompress_entry_len (
             HANDLE_T       h_entry,    /* (I)the handle of the entry. */
             SIZE_T*        pz_dest_len /* (O)specify the actual length, which is needed to decompress the entry data. */
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_query_info
 *              This API will query information of the archive. 
 *  @param [in] h_archive        The handle of the archive.
 *  @param [in] e_type           Specified the type of the query operation.
 *  @param [in] pv_filter        Specified the querying filter to query the archive.
 *  @param [out] pv_query_buf        Retrieve the query information in the buffer.
 *  @param [in][out] pz_query_buf_len    Specified the actual size of query information needed.
 *  @return Return the error code.             
 *  @retval CLR_OK                    The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG                The argument pv_query_buf, pv_filter or pz_query_buf_len contain a NULL pointer or e_type is out of range.
 *  @retval CLR_INV_HANDLE            The handle is not valid any more.
 *  @retval CLR_INSUFFICIENT_BUFFER    The destination buffer is insufficient for data querying.
 *  @retval CLR_FCT_NOT_SUPPORT        The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_query_info (
             HANDLE_T               h_archive,       /* (I)the handle of the archive. */
             CL_QUERY_INFO_TYPE_T   e_type,          /* (I)specified the type of the query operation. */
             VOID*                  pv_filter,       /* (I)specified the querying filter to query the archive. */
             VOID*                  pv_query_buf,    /* (O)retrieve the query information in the buffer. */
             SIZE_T*                pz_query_buf_len /* (I/O)specified the length of the query buffer./specified the actual size of query information needed.  */
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_get_query_info_len
 *              This routine will get the length of query information of the archive.
 *  @param [in] h_archive    The handle of the archive.
 *  @param [in] e_type       Specified the type of the query operation.
 *  @param [in] pv_filter    Specified the querying filter to query the archive.
 *  @param [out] pz_query_buf_len    Specified the actual size of query information needed.
 *  @return Return the error code.
 *  @retval CLR_OK                The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG            The argument pv_filter or pz_query_buf_len contain a NULL pointer or e_type is out of range.
 *  @retval CLR_INV_HANDLE        The handle is not valid any more.
 *  @retval CLR_FCT_NOT_SUPPORT    The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_get_query_info_len (
             HANDLE_T               h_archive,       /* (I)the handle of the archive. */
             CL_QUERY_INFO_TYPE_T   e_type,          /* (I)specified the type of the query operation. */
             VOID*                  pv_filter,       /* (I)specified the querying filter to query the archive. */
             SIZE_T*                pz_query_buf_len /* (O)specified the actual size of query information needed. */
             );

/*------------------------------------------------------------------*/
/*! @brief  c_cl_get_num_entries
 *              This API will query information of the archive.
 *  @param [in] h_archive          The handle of the archive.
 *  @param [out] pui4_num_entris   Retrieve the number of entries.
 *  @return Return the error code.
 *  @retval CLR_OK              The routine was successful and the operation has been completed.
 *  @retval CLR_INV_ARG         The argument pui4_num_entries contains a NULL pointer.            
 *  @retval CLR_INV_HANDLE      The handle h_archive is not valid any more.            
 *  @retval CLR_FCT_NOT_SUPPORT    The requested function was not supported.
 */
/*------------------------------------------------------------------*/
extern INT32 c_cl_get_num_entries (
             HANDLE_T   h_archive,       /* (I)the handle of the archive. */
             UINT32*    pui4_num_entris  /* (O)retrieve the number of entries.*/ 
             );

#endif /* _C_CL_H_ */
/*----------------------------------------------------------------------------*/
/*! @} */   /* end of  groupMW_CL*/
/*----------------------------------------------------------------------------*/

