/* 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_xml_api.h 
 *  $RCSfile: $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This header file contains xml specific
 *         definitions, which are exported.
 */
/*----------------------------------------------------------------------------*/

/*!
* @addtogroup  groupMW_INET_XML
* @brief       Provide an external API about XML.
* %XML API would be used by user who wants to parse xml.  
* 
*
* @{
* */

#ifndef _C_XML_API_H
#define _C_XML_API_H

#include "u_xml.h"
/*------------------------------------------------------------------*/
/*! @brief Allocate new XML
 *  @param [in] ps_ele_name -name of xml element
 *  @param [in] ps_ele_value -xml element content
 *  @return new xml element
 */
/*------------------------------------------------------------------*/
extern XML_T*  c_xml_new_element(const CHAR *ps_ele_name, const CHAR *ps_ele_value);

/*------------------------------------------------------------------*/
/*! @brief Add new child XML element to specified parent element
 *  @param [in] pt_xml_ele -parent xml element
 *  @param [in] ps_ele_name -name of child xml element
 *  @param [in] ps_ele_value -child xml element content
 *  @return     child xml element       
 */
/*------------------------------------------------------------------*/
extern XML_T*  c_xml_add_element (XML_T  *pt_xml_ele, const CHAR *ps_ele_name, const CHAR *ps_ele_value);

/*------------------------------------------------------------------*/
/*! @brief Delete specfied element from the xml document
 *  @param [in] pt_xml_ele -element will be deleted
 *  @return      pt_xml_ele - need use c_xml_free to release resource
 */
/*------------------------------------------------------------------*/
extern XML_T*  c_xml_delete_element (XML_T *pt_xml_ele);

/*------------------------------------------------------------------*/
/*! @brief Constructor of XML_Attribute
 *  @param [in] ps_attr_name -name of attribute
 *  @param [in] ps_attr_value -value of attribute
 *  @return      new xml attribute    
 */
/*------------------------------------------------------------------*/
extern XML_ATTRIBUTE_T*  c_xml_new_attribute (const CHAR *ps_attr_name, const CHAR *ps_attr_value);

/*------------------------------------------------------------------*/
/*! @brief Add new XML attribute to specified xml element
 *  @param [in] pt_xml_ele -xml element
 *  @param [in] ps_attr_name -name of new xml attribute
 *  @param [in] ps_attr_value -value of new xml attribute
 *  @return      new xml attribute    
 */
/*------------------------------------------------------------------*/
extern XML_ATTRIBUTE_T*  c_xml_add_attribute (XML_T *pt_xml_ele, const CHAR *ps_attr_name, const CHAR *ps_attr_value);

/*------------------------------------------------------------------*/
/*! @brief Delete xml attribute from specified xml element
 *  @param [in] pt_xml_ele -xml element
 *  @param [in] pt_xml_attr - xml attribute will be deleted
 */
/*------------------------------------------------------------------*/
extern VOID  c_xml_delete_attribute (XML_T *pt_xml_ele, XML_ATTRIBUTE_T *pt_xml_attr);

/*------------------------------------------------------------------*/
/*! @brief Free xml attribute
 *  @param [in] pt_xml_attr -xml attribute
 */
/*------------------------------------------------------------------*/
extern VOID  c_xml_free_attribute (XML_ATTRIBUTE_T  *pt_xml_attr);

/*------------------------------------------------------------------*/
/*! @brief Free xml node
 *  @param [in] pt_xml_node -xml node 
 */
/*------------------------------------------------------------------*/
extern VOID  c_xml_free_node (XML_NODE_T  *pt_xml_node);

/*------------------------------------------------------------------*/
/*! @brief Release the reference of the xml document
 *  @param [in] pt_xml_doc -xml document
 */
/*------------------------------------------------------------------*/
extern VOID  c_xml_free(XML_T  *pt_xml_doc);

/*------------------------------------------------------------------*/
/*! @brief Get child elment from specified parent element by element name
 *  @param [in] pt_xml_ele -parent xml element
 *  @param [in] ps_ele_name -name of child xml element
 *  @return      child element    
 */
/*------------------------------------------------------------------*/
extern XML_T*  c_xml_get_element (XML_T *pt_xml_ele, const CHAR *ps_ele_name);

/*------------------------------------------------------------------*/
/*! @brief Get the root element of xml document
 *  @param [in] pt_xml_doc -xml document
 *  @return      root element   
 */
/*------------------------------------------------------------------*/
extern XML_T*  c_xml_get_first_element (XML_T *pt_xml_doc);

/*------------------------------------------------------------------*/
/*! @brief Get the first element which name equal to specified tag name from xml document
 *  @param [in] pt_xml_doc -xml document
 *  @param [in] ps_tag_name -tag name
 *  @return      xml element   
 */
/*------------------------------------------------------------------*/
extern XML_T*  c_xml_get_first_element_by_tag_name (XML_T *pt_xml_doc, const CHAR *ps_tag_name);

/*------------------------------------------------------------------*/
/*! @brief Get the first element which name equal to specified tag name 
 *              from xml document with namespace
 *  @param [in] pt_xml_doc -xml document
 *  @param [in] ps_xml_ns -namespace
 *  @param [in] ps_ele_name -tag name
 *  @return      xml element    
 */
/*------------------------------------------------------------------*/
extern XML_T*  c_xml_get_first_element_by_tag_name_ns (XML_T *pt_xml_doc, const CHAR *ps_xml_ns, const CHAR *ps_ele_name);

/*------------------------------------------------------------------*/
/*! @brief Get the value of first element which name equal to specified 
 *              tag name from xml document
 *  @param [in] pt_xml_doc -xml document
 *  @param [in] ps_ele_name -tag name
 *  @return      value of xml element   
 */
/*------------------------------------------------------------------*/
extern CHAR *  c_xml_get_first_element_value (XML_T *pt_xml_doc, const CHAR *ps_ele_name);

/*------------------------------------------------------------------*/
/*! @brief Get the attribute of xml element by attribute name
 *  @param [in] pt_xml_ele -xml element
 *  @param [in] ps_attr_name -attribute name
 *  @return      xml attribute
 */
/*------------------------------------------------------------------*/
extern XML_ATTRIBUTE_T*  c_xml_get_attribute (XML_T *pt_xml_ele, const CHAR *ps_attr_name);

/*------------------------------------------------------------------*/
/*! @brief Get the local name of xml element
 *  @param [in] pt_xml_ele -xml element
 *  @return      local name    
 */
/*------------------------------------------------------------------*/
extern CHAR*  c_xml_get_local_name (XML_T *pt_xml_ele);

/*------------------------------------------------------------------*/
/*! @brief Get the uri of namespace
 *  @param [in] pt_xml_ele -xml element
 *  @return      uri     
 */
/*------------------------------------------------------------------*/
extern CHAR*  c_xml_get_namespace_uri (XML_T *pt_xml_ele);

/*------------------------------------------------------------------*/
/*! @brief Get xml elements by tag name
 *  @param [in] pt_xml_doc -xml document
 *  @param [in] ps_tag_name -tag name of xml element 
 *  @return      xml node  
 */
/*------------------------------------------------------------------*/
extern XML_NODE_T*  c_xml_get_elements_by_tag_name (XML_T *pt_xml_doc, const CHAR *ps_tag_name);

/*------------------------------------------------------------------*/
/*! @brief Print XML document to standard out
 *  @param [in] pt_xml_doc -xml document
 */
/*------------------------------------------------------------------*/
extern VOID  c_xml_print (XML_T *pt_xml_doc);

/*------------------------------------------------------------------*/
/*! @brief Return XML document as string data
 *  @param [in] pt_xml_doc -xml document
 *  @return      string buffer which store xml document      
 */
/*------------------------------------------------------------------*/
extern CHAR*   c_xml_print_document (XML_T *pt_xml_doc);

/*------------------------------------------------------------------*/
/*! @brief Copy xml document
 *  @param [in] pt_xml_doc -original xml document
 *  @return      new document     
 */
/*------------------------------------------------------------------*/
extern XML_T*  c_xml_copy (XML_T *pt_xml_doc);

/*------------------------------------------------------------------*/
/*! @brief Create expat XML_Parser, and register xml handler to expat XML_Parser
 *  @param [in,out] pt_user_data -User data
 *  @return      result
 *  @retval      0 -the routine is successful
 *  @retval      -1 -alloc memory error
 */
/*------------------------------------------------------------------*/
extern INT32   c_xml_parse_message_init (XML_USER_DATA_T *pt_user_data);

/*------------------------------------------------------------------*/
/*! @brief parse message
 *  @param [in,out] pt_user_data -User data
 *  @param [in] ps_buf -buffer will be parsed
 *  @param [in] ui4_length -length of ps_buf
 *  @param [in] i4_done -0: ps_buf is not a complete xml document;others : complete
 *  @return      result
 *  @retval      XML_PARSE_FAILURE -parse xml failure
 *  @retval      XML_SUCCESS -the routine is successful
 */
/*------------------------------------------------------------------*/
extern INT32   c_xml_parse_message (XML_USER_DATA_T  *pt_user_data, CHAR *ps_buf, UINT32 ui4_length, INT32 i4_done);

/*------------------------------------------------------------------*/
/*! @brief Clean up user data after parse
 *  @param [in] pt_user_data -User data
 */
/*------------------------------------------------------------------*/
extern VOID    c_xml_parse_message_done (XML_USER_DATA_T  *pt_user_data);

/*------------------------------------------------------------------*/
/*! @brief XML parse against to the buffer
 *  @param [in] ps_buf -buffer will be parsed
 *  @param [in] ui4_length -length of ps_buf
 *  @param [out] ppt_out_xml_doc -xml documet
 *  @return      result
 *  @retval      XML_PARSE_FAILURE -parse xml failure
 *  @retval      XML_INVALID_STATE_ERR -parse xml result document is NULL
 *  @retval      XML_SUCCESS -the routine is successful
 */
/*------------------------------------------------------------------*/
extern INT32   c_xml_parse_buffer(CHAR *ps_buf, UINT32  ui4_length, XML_T **ppt_out_xml_doc);

/*------------------------------------------------------------------*/
/*! @brief XML parse string
 *  @param [in] ps_str -string will be parsed
 *  @param [out] ppt_out_xml_doc -xml documet
 *  @return      result
 *  @retval      XML_PARSE_FAILURE -parse xml failure
 *  @retval      XML_INVALID_STATE_ERR -parse xml result document is NULL
 *  @retval      XML_SUCCESS -the routine is successful
 */
/*------------------------------------------------------------------*/
extern INT32   c_xml_parse_str(CHAR * ps_str,XML_T ** ppt_out_xml_doc);

#endif

/*! @} */
