/* 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_nwl.h 
 *  $File: //DTV/PROD_BR/DTV_X_IDTV1501/apollo/middleware/public/nwl/c_nwl.h $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This header file contains Network list related API definitions,
 *         which are exported to applications.
 *
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_NWL_H_
#define _C_NWL_H_
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_NWL
 *  @{
 */
/*----------------------------------------------------------------------------*/

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

#include "u_nwl.h"


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

/*------------------------------------------------------------------*/
/*! @brief  Create a NWL object and return a handle to this NWL object.
 *  @param  [in]  ps_nwl_name       - Name of the NWL object.
 *  @param  [in]  ui2_nwl_id        - Unique id for the NWL object.
 *                                    The limit for NWL ID is between 1 and
 *                                    65535.
 *  @param  [in]  e_mem_policy      - Memory policy: NWL_MEM_STATIC or
 *                                    NWL_MEM_DYNAMIC
 *  @param  [in]  ui2_max_nb_rec    - Specifies the maximum number of NWL record
 *                                    (for NWL_MEM_STATIC), or it specifies
 *                                    number of NWL 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 NWL handle when the NWL
 *                                    object has been modified.  If NULL, then
 *                                    no notification function will be called.
 *  @param  [out] ph_nwl            - Handle to the NWL object.
 *  @see    c_nwl_open
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL object is created successfully.
 *  @retval NWLR_INV_ARG        - 'ui2_nwl_id' is 0, or ph_nwl is NULL, or
 *                                ps_nwl_name is 0.
 *  @retval NWLR_OUT_OF_HANDLE  - Cannot get a handle.
 *  @retval NWLR_FAIL           - The specified 'ps_nwl_name' or 'ui2_nwl_id'
 *                                value is not unique (e.g., it is currently
 *                                been used), or limit of the number of NWL
 *                                objects that can be created is reached.
 *  @retval NWLR_OUT_OF_MEM     - Not enough memory to create NWL object.
 *  @retval NWLR_INV_ARG        - 'ps_nwl_name' or 'ph_nwl' is NULL.
 *  @retval NWLR_AEE_OUT_OF_RESOURCES   - Can not allocate AEE resources.
 *  @retval NWLR_AEE_NO_RIGHTS  - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_create (const CHAR*       ps_nwl_name,
                           UINT16            ui2_nwl_id,
                           NWL_MEM_POLICY_T  e_mem_policy,
                           UINT16            ui2_max_nb_rec,
                           VOID*             pv_tag,
                           x_nwl_nfy_fct     pf_nfy,
                           HANDLE_T*         ph_nwl);

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

/*------------------------------------------------------------------*/
/*! @brief  This function gets a handle to the specified NWL database
 *          object by its ID value.
 *  @param  [in]  ui2_nwl_id        - Specifies the NWL object identifier value.
 *                                    The limit for NWL 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 NWL database.  If NULL, then
 *                                    no notification function will be called.
 *  @param  [out] ph_nwl            - Pointer to the handle created.
 *  @see    c_nwl_open_by_name
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL handle is returned.
 *  @retval NWLR_OUT_OF_HANDLE  - No more handle available.
 *  @retval NWLR_OUT_OF_MEM     - Not enough memory to create the NWL control
 *                                structure.
 *  @retval NWLR_NOT_FOUND      - The specified NWL database object id (e.g.
 *                                'ui2_nwl_id') is not found.
 *  @retval NWLR_INV_ARG        - 'ph_nwl' is NULL.
 *  @retval NWLR_AEE_OUT_OF_RESOURCES   - Can not allocate AEE resources.
 *  @retval NWLR_AEE_NO_RIGHTS  - No right for the AEE resources.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_open (UINT16         ui2_nwl_id,
                         VOID*          pv_tag,
                         x_nwl_nfy_fct  pf_nfy,
                         HANDLE_T*      ph_nwl);

/*------------------------------------------------------------------*/
/*! @brief  This function frees the specified handle to the NWL
 *          database object.
 *  @param  [in]  h_nwl             - Handle to NWL database object.
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL handle is freed.
 *  @retval NWLR_INV_HANDLE     - Bad handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_close (HANDLE_T  h_nwl);

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

/*------------------------------------------------------------------*/
/*! @brief  This function adds a new network record to the NWL
 *          database object.  The NWL library will make copy of
 *          the record content from the address location pointed to
 *          by the 'pt_nwl_rec'.  The 'ui2_nwl_rec_id' field in
 *          the 'pt_nwl_rec' structure specifies the key field of the
 *          network record to be added to the database.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  pt_nwl_rec        - Pointer to the network record structure
 *                                    to be added.
 *  @return Return the error code
 *  @retval NWLR_OK             - Record is successfully added.
 *  @retval NWLR_INV_HANDLE     - Bad NWL handle.
 *  @retval NWLR_OUT_OF_MEM     - Can not allocate memory, add record failed.
 *  @retval NWLR_INV_ARG        - 'pt_nwl_rec' is null.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_add_rec  (HANDLE_T          h_nwl,
                             const NWL_REC_T*  pt_nwl_rec);

/*------------------------------------------------------------------*/
/*! @brief  This function deletes a specified network record from
 *          the NWL.  The record to be deleted is specified by the
 *          network record id.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  ui2_nwl_rec_id    - Specifies the network record to
 *                                    be deleted.
 *  @return Return the error code
 *  @retval NWLR_OK             - Specified record is deleted.
 *  @retval NWLR_INV_HANDLE     - Bad NWL handle.
 *  @retval NWLR_REC_NOT_FOUND  - The specified record to be deleted is not in
 *                                the NWL object.
 *  @retval NWLR_INV_ARG        - 'ui2_nwl_rec_id' is not a valid record id.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_del_rec (HANDLE_T  h_nwl,
                            UINT16    ui2_nwl_rec_id);

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

/*------------------------------------------------------------------*/
/*! @brief  This API queries the range (FIRST, LAST, or NEXT) of
 *          valid network record id values used in the NWL
 *          object.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  e_nwl_qry_option  - Flag to specifies the record id value to
 *                                    be returned. The values are:
 *                                    NWL_FIRST_REC_ID,  NWL_LAST_REC_ID,
 *                                    NWL_NEXT_REC_ID.
 *  @param  [out] pui2_rec_id       - Contain the network record id
 *  value.
 *  @return Return the error code
 *  @retval NWLR_OK                 - NWL record id return.
 *  @retval NWLR_INV_HANDLE         - Bad NWL handle.
 *  @retval NWLR_INV_ARG            - 'pui2_rec_id' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_qry_rec_id (HANDLE_T          h_nwl,
                               NWL_REC_ID_QRY_T  e_nwl_qry_option,
                               UINT16*           pui2_rec_id);

/*------------------------------------------------------------------*/
/*! @brief  This function locks the NWL object.   The function blocks
 *          until the lock is acquired.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @see    c_nwl_unlock, c_nwl_read_lock
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL is locked.
 *  @retval NWLR_INV_HANDLE     - Bad NWL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_lock (HANDLE_T  h_nwl);

/*------------------------------------------------------------------*/
/*! @brief  This function unlocks the NWL database.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @see    c_nwl_lock
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL database is unlocked.
 *  @retval NWLR_INV_HANDLE     - Bad NWL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_unlock (HANDLE_T  h_nwl);

/*------------------------------------------------------------------*/
/*! @brief  This function acquires the read-lock on the NWL object.
 *          The function blocks until the lock is acquired.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @see    c_nwl_read_unlock, c_nwl_lock
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL is locked.
 *  @retval NWLR_INV_HANDLE     - Bad NWL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_read_lock (HANDLE_T  h_nwl);

/*------------------------------------------------------------------*/
/*! @brief  This function releases the read-lock on the NWL database.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL database is unlocked.
 *  @retval NWLR_INV_HANDLE     - Bad NWL handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_read_unlock (HANDLE_T  h_nwl);

/*------------------------------------------------------------------*/
/*! @brief  This API gets a specific record stored in the NWL database
 *          object.    The search parameter is specified by the
 *          'ui2_nwl_rec_id' value.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  ui2_nwl_rec_id    - Specifies the network record id.
 *  @param  [out] pt_nwl_rec        - Pointer to a network record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    network record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the NWL database object is incremented each time when
 *          a modification takes place.
 *  @return Return the error code
 *  @retval NWLR_OK             - Data from the specified record is returned.
 *  @retval NWLR_INV_HANDLE     - Bad handle.
 *  @retval NWLR_REC_NOT_FOUND  - No record matching the search parameter
 *                                ('ui2_nwl_rec_id')  is found.
 *  @retval NWLR_INV_ARG        - 'pui4_ver_id' or 'pt_nwl_rec' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_get_rec (HANDLE_T    h_nwl,
                            UINT16      ui2_nwl_rec_id,
                            NWL_REC_T*  pt_nwl_rec,
                            UINT32*     pui4_ver_id);

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

/*------------------------------------------------------------------*/
/*! @brief  This API gets a specific record stored in the NWL database
 *          object by its index.  Maximum available index is obtained
 *          by calling x_nwl_get_num_rec.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  ui2_idx           - Index for iteration.
 *  @param  [out] pt_nwl_rec        - Pointer to a network record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    network record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the NWL database object is incremented each time when
 *          a modification takes place.
 *  @return Return the error code
 *  @retval NWLR_OK             - Data from the specified record is returned.
 *  @retval NWLR_INV_HANDLE     - Bad handle.
 *  @retval NWLR_REC_NOT_FOUND  - Specified record is not found.
 *  @retval NWLR_INV_ARG        - 'pui4_ver_id' or 'pt_nwl_rec' is NULL.
 *  @retval NWLR_MODIFIED       - The database has been modified.  The
 *                                'pui4_ver_id' passed into the API and the
 *                                internal database version id are not the same.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_get_rec_by_rec_idx (HANDLE_T    h_nwl,
                                       UINT16      ui2_idx,
                                       NWL_REC_T*  pt_nwl_rec,
                                       UINT32*     pui4_ver_id);

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

/*------------------------------------------------------------------*/
/*! @brief  This function returns the number of records matching the
 *          given network ID for the specified NWL.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  ui2_network_id    - Specifies the network id.
 *  @param  [out] pui2_num_recs     - Pointer to a variable for the number of
 *                                    records with matching network ID in the
 *                                    NWL.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the NWL database object.
 *  @return Return the error code
 *  @retval NWLR_OK             - Number of records in the specified NWL is
 *                                returned.
 *  @retval NWLR_INV_HANDLE     - Bad 'h_nwl' handle.
 *  @retval NWLR_INV_ARG        - 'pui2_num_recs' or 'pui4_ver_id' is a NULL
 *                                pointer.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_get_num_rec_by_nw_id(HANDLE_T  h_nwl,
                                        UINT16    ui2_network_id,
                                        UINT16*   pui2_num_recs,
                                        UINT32*   pui4_ver_id);

/*------------------------------------------------------------------*/
/*! @brief  This API gets a specific record stored in the NWL database
 *          object.    The search parameter is specified by the
 *          'ui2_satl_id' & 'ui2_satl_rec_id' value.  If there are multiple
 *          records matching the search parameter, the caller can use
 *          ui2_idx to iterate over records with the positive match.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  ui2_satl_id       - Specifies the SATL id.
 *  @param  [in]  ui2_satl_rec_id   - Specifies the SATL record id.
 *  @param  [in]  ui2_idx           - Index for iteration.
 *  @param  [out] pt_nwl_rec        - Pointer to a network record structure.
 *                                    This structure must be allocated by the
 *                                    caller.  On return, it is filled with
 *                                    network record information.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the database object.
 *  @note   Version id of the NWL database object is incremented each time when
 *          a modification takes place.
 *  @return Return the error code
 *  @retval NWLR_OK             - Data from the specified record is returned.
 *  @retval NWLR_INV_HANDLE     - Bad handle.
 *  @retval NWLR_REC_NOT_FOUND  - Specified record is not found.
 *  @retval NWLR_INV_ARG        - 'pui4_ver_id' or 'pt_nwl_rec' is NULL.
 *  @retval NWLR_MODIFIED       - The database has been modified.  The
 *                                'pui4_ver_id' passed into the API and the
 *                                internal database version id are not the same.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_get_rec_by_sat (HANDLE_T    h_nwl,
                                   UINT16      ui2_satl_id,
                                   UINT16      ui2_satl_rec_id,
                                   UINT16      ui2_idx,
                                   NWL_REC_T*  pt_nwl_rec,
                                   UINT32*     pui4_ver_id);

/*------------------------------------------------------------------*/
/*! @brief  This function returns the number of records matching the
 *          given SATL record for the specified NWL.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  ui2_satl_id       - Specifies the SATL id.
 *  @param  [in]  ui2_satl_rec_id   - Specifies the SATL record id.
 *  @param  [out] pui2_num_recs     - Pointer to a variable for the number of
 *                                    records with matching network ID in the
 *                                    NWL.
 *  @param  [out] pui4_ver_id       - Pointer to a variable holding version id
 *                                    of the NWL database object.
 *  @return Return the error code
 *  @retval NWLR_OK             - Number of records in the specified NWL is
 *                                returned.
 *  @retval NWLR_INV_HANDLE     - Bad 'h_nwl' handle.
 *  @retval NWLR_INV_ARG        - 'pui2_num_recs' or 'pui4_ver_id' is a NULL
 *                                pointer.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_get_num_rec_by_sat (HANDLE_T  h_nwl,
                                       UINT16    ui2_satl_id,
                                       UINT16    ui2_satl_rec_id,
                                       UINT16*   pui2_num_recs,
                                       UINT32*   pui4_ver_id);

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

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

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

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

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

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

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

extern INT32 c_nwl_init_mem_dump_64     (NWL_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 NWLR_OK             - Success.
 *  @retval NWLR_INV_ARG        - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_free_mem_dump     (NWL_MEM_DUMP_T*        pt_mem_dump);

extern INT32 c_nwl_free_mem_dump_64     (NWL_MEM_DUMP_EX_T*        pt_mem_dump);

/*------------------------------------------------------------------*/
/*! @brief  This API dumps the specified NWL database into the specified
 *          structure, which could be later used for c_nwl_load_from_mem.
 *          The memory dump structure should be initialized before dumping.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [out] pt_mem_dump       - Pointer to the memory dump structure.
 *  @see    c_nwl_load_from_mem
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL database successfully dumped.
 *  @retval NWLR_INV_HANDLE     - Bad handle.
 *  @retval NWLR_INV_ARG        - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_dump_to_mem       (HANDLE_T               h_nwl,
                                      NWL_MEM_DUMP_T*        pt_mem_dump);

extern INT32 c_nwl_dump_to_mem_64       (HANDLE_T               h_nwl,
                                      NWL_MEM_DUMP_EX_T*        pt_mem_dump);

/*------------------------------------------------------------------*/
/*! @brief  This API loads the NWL database from the specified memory
 *          dump structure, whose data comes from a previous call to
 *          c_nwl_load_from_mem.
 *  @param  [in]  h_nwl             - Handle to the NWL object.
 *  @param  [in]  pt_mem_dump       - Pointer to the memory dump structure.
 *  @see    c_nwl_dump_to_mem, c_nwl_free_mem_dump
 *  @return Return the error code
 *  @retval NWLR_OK             - NWL database successfully loaded.
 *  @retval NWLR_INV_HANDLE     - Bad handle.
 *  @retval NWLR_INV_ARG        - 'pt_mem_dump' is NULL.
 */
/*------------------------------------------------------------------*/
extern INT32 c_nwl_load_from_mem     (HANDLE_T               h_nwl,
                                      NWL_MEM_DUMP_T*        pt_mem_dump);

extern INT32 c_nwl_load_from_mem_64     (HANDLE_T               h_nwl,
                                      NWL_MEM_DUMP_EX_T*        pt_mem_dump);

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