/*
 * Copyright (c) 2016 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 rtixmlutils_parser_h
#define rtixmlutils_parser_h

#include "rtixmlutils/rtixmlutils_dll.h"
#include "rtixmlutils/rtixmlutils_object.h"

#ifdef __cplusplus
        extern "C" {
#endif

/*
 * --- RTIXMLUTILSParser ------------------------------------------------------
 */

/** \ingroup RTIXMLUTILSParserModule
 *
 * @brief Parses the XML content in the specified file.
 *
 * The operation returns the root RTIXMLUTILSObject on success or NULL
 * otherwise. The returned RTIXMLUTILSObject can be freed by calling
 * RTIXMLUTILSParser_freeDom.
 *
 * @param fileName  The absolute or relative path to the file with the XML
 *                  content.
 *
 * @return The root RTIXMLUTILSObject representing the specified XML content
 *         or NULL on error.
 *
 * @see RTIXMLUTILSParser_freeDom
 */
extern RTIXMLUTILSDllExport
RTIBool RTIXMLUTILSParser_parseFile(
        struct RTIXMLUTILSObject **root,
        const char *fileName);

/*i \ingroup
 *
 * @brief Parses XML content represented in the specified string.
 *
 * The operation returns the root RTIXMLUTILSObject on success or NULL
 * otherwise. The returned RTIXMLUTILSObject can be freed by calling
 * RTIXMLUTILSParser_freeDom.
 *
 * @param xmlString The string with the XML content to be parsed.
 *
 * @return The root RTIXMLUTILSObject representing the specified XML content
 *         or NULL on error.
 *
 * @see RTIXMLUTILSParser_freeDom
 *
 */
extern RTIXMLUTILSDllExport
RTIBool RTIXMLUTILSParser_parseString(
        struct RTIXMLUTILSObject **root,
        const char *xmlString);


/*i \ingroup
 *
 * @brief Preprocesses the XML content represented in the specified
 * string array. The operation will concatenate the strings in the
 * array into a single string, and preprocess it remove xmlns references.
 *
 * @param xmlStringArray The array of strings that define the XML content
 *        to be preprocessed.
 * @param xmlStringArrayLength  The length of the array.
 *
 * @return A pointer to the dynamically-allocated string containing
 *         the preprocessed XML string, or null if there was an error
 *         while preprocessing the string array. The caller is responsible
 *         for calling RTIOsapiHeap_freeString when the string is not needed
 *         any more.
 */
extern RTIXMLUTILSDllExport char *RTIXMLUTILSParser_preprocessStringArray(
        const char *xmlStringArray[],
        int xmlStringArrayLength);


/*i \ingroup
 *
 * @brief Parses XML content represented in the specified string array.
 *
 * The operation returns the root RTIXMLUTILSObject on success or NULL
 * otherwise. The returned RTIXMLUTILSObject can be freed by calling
 * RTIXMLUTILSParser_freeDom.
 *
 * @param xmlStringArray The array of strings that define the XML content
 *                       to be parsed.
 * @param xmlStringArrayLength  The length of the array.
 *
 * @return The root RTIXMLUTILSObject representing the specified XML content
 *         or NULL on error.
 *
 * @see RTIXMLUTILSParser_freeDom
 *
 */
extern RTIXMLUTILSDllExport
RTIBool RTIXMLUTILSParser_parseStringArray(
        struct RTIXMLUTILSObject **root,
        const char *xmlStringArray[],
        int xmlStringArrayLength);

/*i \ingroup
 *
 * @brief Parses XML content represented by the specified URL group.
 *
 * An URL group can be specified in three ways:
 * - As a single file URL
 *   Example: file:///home/user/file.xml
 * - As a single string URL
 *   Example: str:://"<root><other></other></root>"
 * - As a sequence of file URLs and/or string URLs. A sequence of URLs is
 * always delimited by '[' ']' an each URL is separated by '|'.
 *   Example: [file:///home/user/file.xml|str:://"<root><other></other></root>"]
 *
 * The operation returns the root RTIXMLUTILSObject on success or NULL
 * otherwise. The returned RTIXMLUTILSObject can be freed by calling
 * RTIXMLUTILSParser_freeDom.
 *
 * @param urlGroup The URL group that define the XML content to be parsed.
 *
 * @return The root RTIXMLUTILSObject representing the specified XML content
 *         or NULL on error.
 *
 * @see RTIXMLUTILSParser_parseFile
 * @see RTIXMLUTILSParser_parseString
 * @see RTIXMLUTILSParser_freeDom
 *
 */
extern RTIXMLUTILSDllExport
RTIBool RTIXMLUTILSParser_parseUrlGroup(
        struct RTIXMLUTILSObject **root,
        const char *urlGroup);

/*i \ingroup
 *
 * @brief Parses XML content represented by the specified list of URL groups.
 *
 * The format of the list is a sequence of groups delimited by ';'.
 * Example: GROUP1 ; GROUP2 ; GROUP3
 *
 * The operation returns the root RTIXMLUTILSObject on success or NULL
 * otherwise. The returned RTIXMLUTILSObject can be freed by calling
 * RTIXMLUTILSParser_freeDom.
 *
 * @param urlGroupList The list of URL groups that define the XML content to
 *                     be parsed.
 *
 * @return The root RTIXMLUTILSObject representing the specified XML content
 *         or NULL on error.
 *
 * @see RTIXMLUTILSParser_parseUrlGroup
 * @see RTIXMLUTILSParser_freeDom
 *
 */
extern RTIXMLUTILSDllExport
RTIBool RTIXMLUTILSParser_parseUrlGroupList(
        struct RTIXMLUTILSObject **root,
        const char *urlGroupList);

/** \ingroup RTIXMLUTILSParserModule
 *
 * @brief Merges a XML DOM of the specified object into the DOM tree of
 * this RTIXMLUTILSObject.
 *
 * This operation will merge the full DOM tree of the specified element,
 * starting from the root element. The operation will move the root's child list
 * of the specified element to the root's child of this object.
 *
 * The root element of both DOM trees must have the same tag name otherwise the
 * operation will fail.
 *
 * A call to RTIXMLUTILSParser_freeDom on the merged tree is required to free
 * up resources.
 *
 * @param dest  The element that belongs to the DOM tree where the the other
 *              DOM is merged.
 * @param from  The element that belongs to the DOM tree to be merged.
 *
 * @return  True on success.
 *
 * @see RTIXMLUTILSObject_copyAsChild
 *
 */
extern RTIXMLUTILSDllExport
RTIBool RTIXMLUTILSParser_mergeRoot(
        struct RTIXMLUTILSObject *dest,
        struct RTIXMLUTILSObject *from);

/** \ingroup RTIXMLUTILSParserModule
 *
 * @brief Deletes the XML subtree delimited by the specified element.
 *
 * This operation can be called on any element belong to an XML DOM generated
 * by any of the parse operations.
 *
 * If the specified element is the root element, then the full XML DOM will
 * be deleted. Otherwise, only the subtree delimited by the specified element
 * as the top will be deleted.
 *
 * @param element   The root element of the subtree to be deleted.
 */
extern RTIXMLUTILSDllExport
void RTIXMLUTILSParser_freeDom(struct RTIXMLUTILSObject *element);

/*
 * --- RTIXMLUTILSGlobals -----------------------------------------------------
 */

/** \ingroup RTIXMLUTILSParserModule
 *
 * The maximum number of string resources that can be registered.
 */
#define RTIXMLUTILS_GLOBALS_STRING_RESOURCES_MAX (8)

/** \ingroup RTIXMLUTILSParserModule
 *
 * @brief Initializes the global state required by the parser module.
 *
 * @mt-safety Unsafe.
 *
 * @return True on success.
 */
extern RTIXMLUTILSDllExport
RTIBool RTIXMLUTILSGlobals_initialize(void);

/** \ingroup RTIXMLUTILSParserModule
 *
 * @brief Finalizes the global state.
 *
 * @mt-safety Unsafe.
 */
extern RTIXMLUTILSDllExport
void RTIXMLUTILSGlobals_finalize(void);

/** \ingroup RTIXMLUTILSParserModule
 *
 * @brief Registers an string resource.
 *
 * A string resource can be registered so that parsers can resolve the include
 * references. The resolution will be determined from the URI specified in the
 * include directive being resolved. The resolution mechanism will find a match
 * between the registered name and the include URI.
 *
 * @param stringResourceName The string resource registration name.
 * @param stringResource The string resource represented as an array of strings.
 * @param stringResource The length of the string resource array.
 *
 * @mt-safety Unsafe.
 *
 * @see RTIXMLUTILS_GLOBALS_STRING_RESOURCES_MAX
 *
 * @return True on success.
 */
extern RTIXMLUTILSDllExport
RTIBool RTIXMLUTILSGlobals_registerStringResource(
        const char *stringResourceName,
        const char *stringResource[],
        int stringResourceLength);


#ifdef __cplusplus
        }	/* extern "C" */
#endif

#endif /* rtixmlutils_parser_h */