/* 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_satl.h
 *  $File: //DTV/PROD_BR/DTV_X_IDTV1501/apollo/middleware/public/satl/c_satl.h $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *    This header file contains Satellite list (SATL) database
 *    API definitions, which are exported to other Middleware components
 *    and applications.
 *         
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_SATL_H_
#define _C_SATL_H_
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_SATL
 *  @{
 */
/*----------------------------------------------------------------------------*/

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

#include "u_satl.h"

/*-------------------------------------------------------------------------
                    functions declarations
 --------------------------------------------------------------------------*/
/*------------------------------------------------------------------*/
/*! @brief  Create a SATL object and return a handle to this SATL object.
 *  @param  [in]  ps_satl_name      - Name of the SATL object.
 *  @param  [in]  ui2_satl_id       - Unique id for the SATL object.
 *                                    The limit for SATL ID is between 1 and
 *                                    65535.
 *  @param  [in]  e_mem_policy      - Memory policy: SATL_MEM_STATIC or
 *                                    SATL_MEM_DYNAMIC
 *  @param  [in]  ui2_max_nb_rec    - Specifies the maximum number of SATL record
 *                                    (for SATL_MEM_STATIC), or it specifies
 *                                    number of SATL 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 SATL handle when the SATL
 *                                    object has been modified.  If NULL, then
 *                                    no notification function will be called.
 *  @param  [out] ph_satl           - Handle to the SATL object.
 *  @see    c_satl_open
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL object is created successfully.
 *  @retval SATLR_INV_ARG       - 'ui2_satl_id' is 0, or ph_satl is NULL, or
 *                                ps_satl_name is 0.
 *  @retval SATLR_OUT_OF_HANDLE - Cannot get a handle.
 *  @retval SATLR_FAIL          - The specified 'ps_satl_name' or 'ui2_satl_id'
 *                                value is not unique (e.g., it is currently
 *                                been used), or limit of the number of SATL
 *                                objects that can be created is reached.
 *  @retval SATLR_OUT_OF_MEM    - Not enough memory to create SATL object.
 *  @retval SATLR_INV_ARG       - 'ps_satl_name' or 'ph_satl' is NULL.
 *  @retval SATLR_AEE_OUT_OF_RESOURCES  - Can not allocate AEE resources.
 *  @retval SATLR_AEE_NO_RIGHTS - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_create
(
    const CHAR*         ps_satl_name,
    UINT16              ui2_satl_id,
    SATL_MEM_POLICY_T   e_mem_policy,
    UINT16              ui2_max_nb_rec,
    VOID*               pv_tag,
    x_satl_nfy_fct      pf_nfy,
    HANDLE_T*           ph_satl
);

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

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

/*------------------------------------------------------------------*/
/*! @brief  This function adds a new service record to the SATL
 *          database object.  The SATL library will make copy of
 *          the record content from the address location pointed to
 *          by the 'pt_satl_rec'. The 'ui2_satl_rec_id' field in
 *          the 'pt_satl_rec' structure specifies the key field of the
 *          service record to be added to the database.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [in]  pt_satl_rec       - Pointer to the service record structure
 *                                    to be added.
 *  @return Return the error code
 *  @retval SATLR_OK            - Record is successfully added.
 *  @retval SATLR_INV_HANDLE    - Bad SATL handle.
 *  @retval SATLR_OUT_OF_MEM    - Can not allocate memory, add record failed.
 *  @retval SATLR_INV_ARG       - 'pt_satl_rec' is null.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_add_rec
(
    HANDLE_T            h_satl,
    const SATL_REC_T*   pt_satl_rec
);

/*------------------------------------------------------------------*/
/*! @brief  This function deletes a specified service record from
 *          the SATL. The record to be deleted is specified by the
 *          satellite record id.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [in]  ui2_satl_rec_id   - Specifies the satellite record to
 *                                    be deleted.
 *  @return Return the error code
 *  @retval SATLR_OK            - Specified record is deleted.
 *  @retval SATLR_INV_HANDLE    - Bad SATL handle.
 *  @retval SATLR_REC_NOT_FOUND - The specified record to be deleted is not in
 *                                the SATL object.
 *  @retval SATLR_INV_ARG       - 'ui2_satl_rec_id' is not a valid record id.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_del_rec
(
    HANDLE_T            h_satl,
    UINT16              ui2_satl_rec_id
);

/*------------------------------------------------------------------*/
/*! @brief  This function updates a Satellite record to the SATL
 *          object. If the key field value (e.g., 'ui2_satl_rec_id' field
 *          in the 'pt_satl_rec' structure) of the input service record
 *          matches an existing record in the SATL object, then the
 *          existing record is over-wrote with the new information,
 *          otherwise a new record is created in the SATL 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 'SATLR_REC_NOT_FOUND' is returned to the caller.
 *          If 'b_must_exist' flag is FALSE, then a new service record
 *          is created if no existing record matching the key field value
 *          is found in the SATL database.
 *
 *          Call to this function must be protected, e.g., the SATL
 *          database object needs to be locked before the call to this
 *          function and unlock after returning from call to this function.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [in]  pt_satl_rec       - Pointer to service record structure.
 *  @param  [in]  b_must_exist      - Boolean flag specifying if the service
 *                                    record to be updated should exist in the
 *                                    SATL database.
 *  @return Return the error code
 *  @retval SATLR_OK            - Record is successfully added/updated.
 *  @retval SATLR_INV_HANDLE    - Bad SATL handle.
 *  @retval SATLR_OUT_OF_MEM    - Not enough memory to create a new SATL record.
 *  @retval SATLR_REC_NOT_FOUND - The specified record is not found
 *                                ('b_must_exist' == TRUE)
 *  @retval SATLR_INV_ARG       - 'pt_satl_rec' is NULL or the pt_satl_rec
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_update_rec
(
    HANDLE_T            h_satl,
    const SATL_REC_T*   pt_satl_rec,
    BOOL                b_must_exist	
);

/*------------------------------------------------------------------*/
/*! @brief  This API queries the range (FIRST, LAST, or NEXT) of
 *          valid satellite record id values used in the SATL
 *          object.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [in]  e_satl_qry_option - Flag to specifies the record id value to
 *                                    be returned. The values are:
 *                                    SATL_FIRST_REC_ID, SATL_LAST_REC_ID,
 *                                    SATL_NEXT_REC_ID.
 *  @param  [out] pui2_rec_id       - Contain the satellite record id
 *  value.
 *  @return Return the error code
 *  @retval SATLR_OK                - SATL record id return.
 *  @retval SATLR_INV_HANDLE        - Bad SATL handle.
 *  @retval SATLR_INV_ARG           - 'pui2_rec_id' is NULL.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_qry_rec_id
(
    HANDLE_T            h_satl,
    SATL_REC_ID_QRY_T   e_satl_qry_option,
    UINT16*             pui2_rec_id	
);

/*------------------------------------------------------------------*/
/*! @brief  This function locks the SATL object.   The function blocks
 *          until the lock is acquired.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @see    c_satl_unlock, c_satl_read_lock
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL is locked.
 *  @retval SATLR_INV_HANDLE    - Bad SATL handle.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_lock
(
    HANDLE_T            h_satl
);

/*------------------------------------------------------------------*/
/*! @brief  This function unlocks the SATL database.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @see    c_satl_lock
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL database is unlocked.
 *  @retval SATLR_INV_HANDLE    - Bad SATL handle.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_unlock
(
    HANDLE_T            h_satl
);

/*------------------------------------------------------------------*/
/*! @brief  This function acquires the read-lock on the SATL object.
 *          The function blocks until the lock is acquired.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @see    c_satl_read_unlock, c_satl_lock
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL is locked.
 *  @retval SATLR_INV_HANDLE    - Bad SATL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_satl_read_lock
(
    HANDLE_T            h_satl
);

/*------------------------------------------------------------------*/
/*! @brief  This function releases the read-lock on the SATL database.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL database is unlocked.
 *  @retval SATLR_INV_HANDLE    - Bad SATL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_satl_read_unlock
(
    HANDLE_T            h_satl
);

/*------------------------------------------------------------------*/
/*! @brief  This API loads a specified SATL object from file system
 *          into memory, and returns a handle to the newly created
 *          SATL object.
 *  @param  [in]  h_dir             - Handle to the parent directory of the file
 *                                    specified by the path 'ps_satl_path'. If
 *                                    'ps_satl_path' is an absolute path, then
 *                                    this argument should be set to
 *                                    'FM_ROOT_HANDLE'.
 *  @param  [in]  ps_satl_path      - Specifies the path to the file where the
 *                                    SATL objects are stored in the file system.
 *  @param  [in]  ui2_satl_id       - Specifies the SATL id to load from the file
 *                                    system.  The limit for SATL ID is between 1
 *                                    and 65535.
 *  @param  [in]  ps_satl_name      - Specifies the name for the SATL object.  If
 *                                    null string is specified, then the default
 *                                    name stored in the file system is used to
 *                                    create the SATL 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 SATL handle when the SATL
 *                                    object has been modified by another
 *                                    client.  If NULL, then no notification
 *                                    function will be called.
 *  @param  [out] ph_satl           - On return, contain the handle to the SATL
 *                                    object created from file system.
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL object is created.
 *  @retval SATLR_NOT_FOUND     - 'ui2_satl_id' is not found or 'ps_satl_path'
 *                                does not exist.
 *  @retval SATLR_OUT_OF_HANDLE - Cannot get a handle.
 *  @retval SATLR_OUT_OF_MEM    - Not enough memory to create SATL object.
 *  @retval SATLR_FAIL          - The specified 'ps_satl_name' or 'ui2_satl_id'
 *                                value is not unique.
 *  @retval SATLR_INV_ARG       - 'ph_satl' or 'ps_satl_path' is NULL.
 *  @retval SATLR_AEE_OUT_OF_RESOURCES  - Can not allocate AEE resources.
 *  @retval SATLR_AEE_NO_RIGHTS - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_fs_load
(
    HANDLE_T            h_dir,
    const CHAR*         ps_satl_path,
    UINT16              ui2_satl_id,
    const CHAR*	        ps_satl_name,
    VOID*               pv_tag,
    x_satl_nfy_fct      pf_nfy,
    HANDLE_T*           ph_satl
);

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

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

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

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

/*------------------------------------------------------------------*/
/*! @brief  This function gets a handle to the specified SATL database
 *          object by its ID value.
 *  @param  [in]  ui2_satl_id       - Specifies the SATL object identifier value.
 *                                    The limit for SATL 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 SATL database.  If NULL, then
 *                                    no notification function will be called.
 *  @param  [out] ph_satl           - Pointer to the handle created.
 *  @see    c_satl_open_by_name
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL handle is returned.
 *  @retval SATLR_OUT_OF_HANDLE - No more handle available.
 *  @retval SATLR_OUT_OF_MEM    - Not enough memory to create the SATL control
 *                                structure.
 *  @retval SATLR_NOT_FOUND     - The specified SATL database object id (e.g.
 *                                'ui2_satl_id') is not found.
 *  @retval SATLR_INV_ARG       - 'ph_satl' is NULL.
 *  @retval SATLR_AEE_OUT_OF_RESOURCES  - Can not allocate AEE resources.
 *  @retval SATLR_AEE_NO_RIGHTS - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_open
(
    UINT16              ui2_satl_id,
    VOID*               pv_tag,
    x_satl_nfy_fct      pf_nfy,
    HANDLE_T*           ph_satl
);

/*------------------------------------------------------------------*/
/*! @brief  This function gets a handle to the specified SATL database
 *          object by its name.
 *  @param  [in]  ps_satl_name      - Specifies the SATL object name (16 char
 *                                    max).
 *  @param  [in]  pv_tag            - A private tag value associated with the
 *                                    calling client.
 *  @param  [in]  pf_nfy            - Pointer to a caller provided notification
 *                                    function.  The notification function is
 *                                    called in the context of the thread that
 *                                    modifies (update, add, delete) the SATL
 *                                    database.  If NULL, then no notification
 *                                    function will be called.
 *  @param  [out] ph_satl           - Pointer to the handle created.
 *  @see    c_satl_open
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL handle is returned.
 *  @retval SATLR_OUT_OF_HANDLE - No more handle available.
 *  @retval SATLR_OUT_OF_MEM    - Not enough memory to create the SATL
 *                                handle structure.
 *  @retval SATLR_NOT_FOUND     - The specified SATL database object name (e.g.,
 *                                ps_satl_name) is not found.
 *  @retval SATLR_INV_ARG       - 'ph_satl' or 'ps_satl_name' is NULL.
 *  @retval SATLR_AEE_OUT_OF_RESOURCES  - Can not allocate AEE resources.
 *  @retval SATLR_AEE_NO_RIGHTS - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_open_by_name
(
    const CHAR*         ps_satl_name,
    VOID*               pv_tag,
    x_satl_nfy_fct      pf_nfy,
    HANDLE_T*		ph_satl
);

/*------------------------------------------------------------------*/
/*! @brief  This function frees the specified handle to the SATL
 *          database object.
 *  @param  [in]  h_satl            - Handle to SATL database object.
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL handle is freed.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_close
(
    HANDLE_T            h_satl
);

/*------------------------------------------------------------------*/
/*! @brief  This function gets the SATL ID and SATL name for the
 *          specified handle.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [out] pui2_satl_id      - Pointer to SATL ID variable.  On return it
 *                                    contains the SATL ID value for this handle.
 *  @param  [out] ps_satl_name      - Pointer to a char array variable (the size
 *                                    of this char array should be at least
 *                                    MAX_SATL_NAME_LEN+1). On return, this
 *                                    array contains the name of the SATL object.
 *  @return Return the error code
 *  @retval SATLR_OK            - Information about this handle (satl id and satl
 *                                name) is returned.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 *  @retval SATLR_INV_ARG       - 'pui2_satl_id' or 'ps_satl_name' is NULL.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_get_handle_info
(
    HANDLE_T            h_satl,
    UINT16*             pui2_satl_id,
    CHAR*               ps_satl_name
);

/*------------------------------------------------------------------*/
/*! @brief  This API gets a specific record stored in the SATL database
 *          object.    The search parameter is specified by the
 *          'ui2_satl_rec_id' value.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [in]  ui2_satl_rec_id   - Specifies the service record id.
 *  @param  [out] pt_satl_rec       - Pointer to a service record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    service record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the SATL database object is incremented each time when
 *          a modification takes place.
 *  @return Return the error code
 *  @retval SATLR_OK            - Data from the specified record is returned.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 *  @retval SATLR_REC_NOT_FOUND - No record matching the search parameter
 *                                ('ui2_satl_rec_id') is found.
 *  @retval SATLR_INV_ARG       - 'pui4_ver_id' or 'pt_satl_rec' is NULL.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_get_rec
(
    HANDLE_T            h_satl,
    UINT16              ui2_satl_rec_id,
    SATL_REC_T*         pt_satl_rec,
    UINT32*             pui4_ver_id
);

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

/*------------------------------------------------------------------*/
/*! @brief  This API returns satellite list record entry from the
 *          SATL database object by its index. Maximum index is obtained
 *          by calling c_satl_get_num_recs.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [in]  ui2_idx           - An idx to get the next SATL record.
 *                                    For example: 0 will the first SATL record,
 *                                    and 1 will be second, and so on.
 *  @param  [out] pt_satl_rec       - Pointer to a service record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    service record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the SATL database object is incremented each time when
 *          a modification takes place.
 *  @return Return the error code
 *  @retval SATLR_OK            - Data from the specified record is returned.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 *  @retval SATLR_REC_NOT_FOUND - No record matching the search index
 *                                ('ui2_idx') is found.
 *  @retval SATLR_INV_ARG       - 'pui4_ver_id' or 'pt_satl_rec' is NULL.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_get_rec_by_rec_idx
(
    HANDLE_T            h_satl,
    UINT16              ui2_idx,
    SATL_REC_T*         pt_satl_rec,
    UINT32*             pui4_ver_id
);

/*------------------------------------------------------------------*/
/*! @brief  This API pre-sets the SATL_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 SATL_REC_T structure for
 *          backward compatibility in the future.
 *
 *          For example, if a new field is added to the SATL record structure.
 *          At the runtime, if the new field in the SATL_REC_T structure passed
 *          into SATL library contain 0xFF, then we know the caller has not been
 *          re-compile with the new SATL module.
 *  @param  [out] pt_satl_rec       - Pointer to a SATL record structure.
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL library is initialized successfully.
 *  @retval SATLR_INV_ARG       - 'pt_satl_rec' is a NULL pointer.
 */
/*------------------------------------------------------------------*/
extern
INT32 c_satl_rec_init
(
    SATL_REC_T*		pt_satl_rec
);

/*---------------------------------------------------------------a---*/
/*! @brief  This API specifies a entry position in SATL records,
 *          which will read when API c_satl_read_cursor() is called.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [in]  e_pos             - Position of the SATL record to read.
 *  @see    c_satl_read_cursor
 *  @return Return the error code
 *  @retval SATLR_OK            - Data from the specified record is returned.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 *  @retval SATLR_INV_ARG       - 'e_pos' is invalid.
 */
/*------------------------------------------------------------------*/
extern INT32 c_satl_set_cursor
(
    HANDLE_T            h_satl,
    SATL_ITERATE_T      e_pos
);

/*------------------------------------------------------------------*/
/*! @brief  This API read the content of a specific record
 *          stored in the SATL database.  The specific record is read
 *          is the record currently pointed by the cursor.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [out] pt_satl_rec       - Pointer to a service record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    service record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the SATL database object is incremented each time when
 *          a modification takes place.
 *  @see    c_satl_set_cursor
 *  @return Return the error code
 *  @retval SATLR_OK            - Data from the specified record is returned.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 *  @retval SATLR_INV_ARG       - 'pui4_ver_id' or 'pt_satl_rec' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_satl_read_cursor
(
    HANDLE_T            h_satl,
    SATL_REC_T*         pt_satl_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 SATL
 *          records.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [out] pui4_ver_id       - Contains the version id of the SATL
 *                                    database object.
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL record are sorted and internal sort list
 *                                is updated.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_satl_sort_rec
(
    HANDLE_T			h_satl,
    UINT32*             pui4_ver_id 
);

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

extern INT32 c_satl_init_mem_dump_64
(
    SATL_MEM_DUMP_EX_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 SATLR_OK            - Success.
 *  @retval SATLR_INV_ARG       - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_satl_free_mem_dump
(
    SATL_MEM_DUMP_T*       pt_mem_dump
);

extern INT32 c_satl_free_mem_dump_64
(
    SATL_MEM_DUMP_EX_T*       pt_mem_dump
);

/*------------------------------------------------------------------*/
/*! @brief  This API dumps the specified SATL database into the specified
 *          structure, which could be later used for c_satl_load_from_mem.
 *          The memory dump structure should be initialized before dumping.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [out] pt_mem_dump       - Pointer to the memory dump structure.
 *  @see    c_satl_load_from_mem
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL database successfully dumped.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 *  @retval SATLR_INV_ARG       - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_satl_dump_to_mem
(
    HANDLE_T               h_satl,
    SATL_MEM_DUMP_T*       pt_mem_dump
);

extern INT32 c_satl_dump_to_mem_64
(
    HANDLE_T               h_satl,
    SATL_MEM_DUMP_EX_T*       pt_mem_dump
);

/*------------------------------------------------------------------*/
/*! @brief  This API loads the SATL database from the specified memory
 *          dump structure, whose data comes from a previous call to
 *          c_satl_load_from_mem.
 *  @param  [in]  h_satl            - Handle to the SATL object.
 *  @param  [in]  pt_mem_dump       - Pointer to the memory dump structure.
 *  @see    c_satl_dump_to_mem, c_satl_free_mem_dump
 *  @return Return the error code
 *  @retval SATLR_OK            - SATL database successfully loaded.
 *  @retval SATLR_INV_HANDLE    - Bad handle.
 *  @retval SATLR_INV_ARG       - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_satl_load_from_mem
(
    HANDLE_T               h_satl,
    SATL_MEM_DUMP_T*       pt_mem_dump
);

extern INT32 c_satl_load_from_mem_64
(
    HANDLE_T               h_satl,
    SATL_MEM_DUMP_EX_T*       pt_mem_dump
);

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