/*
 * Copyright (c) 2007-2024 Real-Time Innovations, Inc. All rights reserved.
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or revisions thereof,
 * must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef rtixml_parser_h
#define rtixml_parser_h


/* ---------------------------------------------------------------------- */
/* PARSER CLASS --------------------------------------------------------- */
/* ---------------------------------------------------------------------- */

/*e \file
  \brief XML Parser API
*/

/*e \mainpage
  RTI XML utilities
*/

/*e \defgroup RTIXMLModule RTIXMLModule
  \brief RTI XML utilities
*/

/*e \defgroup RTIXMLParserClass RTIXMLParser
  \ingroup RTIXMLModule

  @brief RTI XML Parser

  The XML parser will parse the input XML returning the root RTIXMLObject.

  The XML parser can parse files, urls, and strings.

  Following there is a code snippet that shows how to use the Parser.

  \b Example:
  \code
  void example( char * inputXML )
  {
    struct RTIXMLParser * parser = NULL;
    struct RTIXMLObject * root = NULL;

    parser = RTIXMLParser_new();

    // Here register parser extensions ...

    root = RTIXMLParser_parseFromFile(parser, NULL, 0, inputXML);
    if (root == NULL) {
        RTIXMLLog_exception( METHOD_NAME,
                             &RTI_LOG_ANY_FAILURE_s,
                             "parsing" );
        RTIXMLParser_delete(parser);
        return 0;
    }

    // Use the returned DOM ...

    RTIXMLParser_delete(parser);
  }
  \endcode
*/

/* ---------------------------------------------------------------------- */
/* INCLUDES, DEFINES ---------------------------------------------------- */
/* ---------------------------------------------------------------------- */

#include "rtixml/rtixml_dll.h"
#include "rtixml/rtixml_extension.h"

#ifdef __cplusplus
    extern "C" {
#endif

/* ---------------------------------------------------------------------- */
/* STRUCTURES ----------------------------------------------------------- */
/* ---------------------------------------------------------------------- */

/*e \ingroup RTIXMLParserClass
  @brief RTIXMLParser class
*/
struct RTIXMLParser;

/* ---------------------------------------------------------------------- */
/* METHODS -------------------------------------------------------------- */
/* ---------------------------------------------------------------------- */

/*e \ingroup RTIXMLParserClass

  @brief Creates a new RTIXMLParser.

  This method creates a new RTIXMLParser.
  The same parser can be used to parse multiple XML files.

  @return The new RTIXMLParser if success. Otherwise, NULL.

  @see RTIXMLParser_delete
*/
extern RTIXMLDllExport struct RTIXMLParser * RTIXMLParser_new(void);

/*e \ingroup RTIXMLParserClass

  @brief Deletes a RTIXMLParser

  This method deletes a RTIXMLParser that was created with RTIXMLParser_new.

  @pre self is not NULL

  @param self \b In. Pointer to the parser.

  @see RTIXMLParser_new
*/
extern RTIXMLDllExport void RTIXMLParser_delete(struct RTIXMLParser *self);

/*e \ingroup RTIXMLParserClass

  @brief Initializes a RTIXMLParser

  @pre self is not NULL

  @param self \b In. Pointer to the parser.

  @return RTI_TRUE if success. Otherwise, RTI_FALSE.

  @see RTIXMLParser_finalize
*/
extern RTIXMLDllExport
RTIBool RTIXMLParser_initialize(struct RTIXMLParser *self);

/*e \ingroup RTIXMLParserClass

  @brief Finalizes a RTIXMLParser

  This method releases the resources associated to the input RTIXMLParser.

  @pre self is not NULL

  @param self \b In. Pointer to the parser.

  @see RTIXMLParser_initialize
*/
extern RTIXMLDllExport void RTIXMLParser_finalize(struct RTIXMLParser *self);

/*e \ingroup RTIXMLParserClass

  @brief Parses a XML file and returns a pointer to the root XML object,
  optionally relaxing DTD validation to allow unexpected tags.

  It is responsability of the user to release the returned DOM using the
  function RTIXMLParser_freeDOM.

  @pre self is not NULL.
  @param dtdStr \b In. Pointer to an array of string pointers containing the DTD
  document

  The DTD document referenced from the DOCTYPE tag in the XML file takes
  precedence over dtdStr.

  @param dtdStrLength \b In. Number of elements in dtdStr
  @param dtdIgnoreUnexpectedElements \b In. Whether tags not specified in the
  DTD should be ignored.
  @pre filename is not NULL.

  @param self \b In. Pointer to the parser.
  @param fileName \b In. The name of the XML file.

  @return The root element of the DOM if success. Otherwise, NULL.

  @see RTIXMLParser_parseFromString_ex
*/
extern RTIXMLDllExport struct RTIXMLObject * RTIXMLParser_parseFromFile_ex(
        struct RTIXMLParser *self,
        const char *dtdStr[],
        unsigned int dtdStrLength,
        RTIBool dtdIgnoreUnexpectedElements,
        const char *fileName,
        struct RTIXMLObject *root,
        void *contextUserData);


/*e \ingroup RTIXMLParserClass

  @brief Parses a XML file and returns a pointer to the root XML object.

  It is responsability of the user to release the returned DOM using the
  function RTIXMLParser_freeDOM.

  @pre self is not NULL.
  @param dtdStr \b In. Pointer to an array of string pointers containing the DTD
  document

  The DTD document referenced from the DOCTYPE tag in the XML file takes
  precedence over dtdStr.

  @param dtdStrLength \b In. Number of elements in dtdStr
  @pre filename is not NULL.

  @param self \b In. Pointer to the parser.
  @param fileName \b In. The name of the XML file.

  @return The root element of the DOM if success. Otherwise, NULL.

  @see RTIXMLParser_parseFromString
*/
extern RTIXMLDllExport struct RTIXMLObject * RTIXMLParser_parseFromFile(
        struct RTIXMLParser *self,
        const char *dtdStr[],
        unsigned int dtdStrLength,
        const char *fileName,
        struct RTIXMLObject *root,
        void *contextUserData);

/*e \ingroup RTIXMLParserClass

  @brief Parses XML data from the input string vector and
  returns a pointer to the root XML object,  optionally relaxing DTD
  validation to allow unexpected tags.

  It is responsability of the user to release the returned DOM using the
  function RTIXMLParser_freeDOM.

  The DTD document referenced from the DOCTYPE tag in the XML file takes
  precedence over dtdStr.

  @pre self is not NULL.
  @pre xmlStr is not NULL
  @pre xmlStrLength is not '0'.
  @pre if dtdStrLength > 0 then dtdStr != NULL

  @param self \b In. Pointer to the parser.
  @param dtdStr \b In. Pointer to an array of string pointers containing the DTD
  document
  @param dtdStrLength \b In. Number of elements in dtdStr
  @param dtdIgnoreUnexpectedElements \b In. Whether tags not specified in the
  DTD should be ignored.
  @param xmlStr \b In. String array to be parsed.
  @param xmlStrLength \b In. Size of the string array.

  @return The root element of the DOM if success. Otherwise, NULL.

  @see RTIXMLParser_parseFromFile
*/
extern RTIXMLDllExport struct RTIXMLObject * RTIXMLParser_parseFromString_ex(
        struct RTIXMLParser *self,
        const char *dtdStr[],
        unsigned int dtdStrLength,
        RTIBool dtdIgnoreUnexpectedTags,
        const char *xmlStr[],
        unsigned int xmlStrLength,
        struct RTIXMLObject *root,
        void *contextUserData);

/*e \ingroup RTIXMLParserClass

  @brief Parses XML data from the input string vector and
  returns a pointer to the root XML object.

  It is responsability of the user to release the returned DOM using the
  function RTIXMLParser_freeDOM.

  The DTD document referenced from the DOCTYPE tag in the XML file takes
  precedence over dtdStr.

  @pre self is not NULL.
  @pre xmlStr is not NULL
  @pre xmlStrLength is not '0'.
  @pre if dtdStrLength > 0 then dtdStr != NULL

  @param self \b In. Pointer to the parser.
  @param dtdStr \b In. Pointer to an array of string pointers containing the DTD
  document
  @param dtdStrLength \b In. Number of elements in dtdStr
  @param xmlStr \b In. String array to be parsed.
  @param xmlStrLength \b In. Size of the string array.

  @return The root element of the DOM if success. Otherwise, NULL.

  @see RTIXMLParser_parseFromFile
*/
extern RTIXMLDllExport struct RTIXMLObject * RTIXMLParser_parseFromString(
        struct RTIXMLParser *self,
        const char *dtdStr[],
        unsigned int dtdStrLength,
        const char *xmlStr[],
        unsigned int xmlStrLength,
        struct RTIXMLObject *root,
        void *contextUserData);

/*e \ingroup RTIXMLParserClass

  @brief Registers a RTIXMLExtensionClass with the parser.

  @pre self is not NULL
  @pre extension is not NULL

  @param self \b In. A pointer to the parser.
  @param extension \b In. The pointer to the extension to be register.

  @return RTI_TRUE if success. Otherwise, RTI_FALSE.

  If the extension already exists, the function returns
  RTI_TRUE and prints a warning
*/
extern RTIXMLDllExport RTIBool RTIXMLParser_registerExtensionClass(
        struct RTIXMLParser *self,
        struct RTIXMLExtensionClass *extension);

/*e \ingroup RTIXMLParserClass

  @brief Unregisters a RTIXMLExtensionClass.

  @pre self is not NULL
  @pre tagName is not NULL

  @param self \b In. A pointer to the parser.
  @param tagName \b In. Tagname associated to the extension class.

  @return Unregistered extension class. NULL if the extension class does not
  exist
*/
extern RTIXMLDllExport
struct RTIXMLExtensionClass * RTIXMLParser_unregisterExtensionClass(
        struct RTIXMLParser *self,
        const char *tagName);

/*e \ingroup RTIXMLParserClass

  @brief Finds a RTIXMLExtensionClass.

  @pre self is not NULL
  @pre tagName is not NULL

  @param self \b In. A pointer to the parser.
  @param tagName \b In. Tagname associated to the extension class.

  @return Extension class. NULL if the extension class is not found
*/
extern RTIXMLDllExport
struct RTIXMLExtensionClass * RTIXMLParser_findExtensionClass(
        struct RTIXMLParser *self,
        const char *tagName);

/*e \ingroup RTIXMLParserClass

  @brief Releases all the resources associated to the input DOM object

  @pre self is not NULL
  @pre dom is not NULL

  @param self \b In. A pointer to the parser.
  @param dom \b In. A pointer to the DOM object.
*/
extern RTIXMLDllExport void RTIXMLParser_freeDOM(
        struct RTIXMLParser *self,
        struct RTIXMLObject *dom);

/*e \ingroup RTIXMLParserClass

  @brief Gets the version of the last XML file parsed by the parser.

  If the version does not exist the function returns NULL.

  @pre self is not NULL

  @param self \b In. A pointer to the parser.

  @return The XML version if it exists. Otherwise, NULL.
*/
extern RTIXMLDllExport const char * RTIXMLParser_getLastXmlVersion(
        struct RTIXMLParser *self);

/** \ingroup RTIXMLParserClass
 * @brief Adds a new entry in the user_environment list of this parser
 *
 * The variable is asserted at the end of the list, overriding the value if the
 * variable already exists.
 */
extern RTIXMLDllExport
RTIBool RTIXMLParser_addUserEnvironmentVariable(
        struct RTIXMLParser *self,
        const char *name,
        const char *value);


#ifdef __cplusplus
  }	/* extern "C" */
#endif
#include "rtixml/rtixml_parser_impl.h"

#endif /* rtixml_parser_h */