/*
 * 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_infrastructure_h
#define rtixml_infrastructure_h

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

/*e \file
  \brief XML Infrastucture
*/

/*e \defgroup RTIXMLInfrastuctureModule RTIXMLInfrastucture
  \ingroup RTIXMLModule
*/

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

#include "stdio.h"

#include "rtixml/rtixml_dll.h"
#include "osapi/osapi_type.h"

#ifdef __cplusplus
    extern "C" {
#endif

  #define RTIXML_XML_BUFFER_SIZE 32768
  #define RTIXML_XML_SMALL_BUFFER_SIZE 2048
  #define RTIXML_XML_MAX_DEPTH 128
  #define RTIXML_MAGIC_NUMBER 0x7344L
  #define RTIXML_INDENT_WIDTH 4
  #define RTIXML_INDENT_CHARACTER ' '
  #define RTIXML_BASE_FORMAT_PI_NAME "rti-baseformat"


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

/*i \ingroup RTIXMLInfrastuctureModule
    Forward declaration
*/
typedef enum RTIXMLErrorKind {
    RTI_XML_NO_ERROR,
    RTI_XML_GENERAL_ERROR,
    RTI_XML_DTD_VALIDATION_ERROR
} RTIXMLErrorKind;

/*i \ingroup RTIXMLInfrastuctureModule
  @brief Byte data format
*/
typedef enum {
    RTI_XML_BYTE_BASE_NONE,
    RTI_XML_BYTE_BASE_HEX,
    RTI_XML_BYTE_BASE_DEC
} RTIXMLByteBase;

/*i \ingroup RTIXMLInfrastuctureModule
    Forward declaration
*/
struct XML_ParserStruct;

/*e \ingroup RTIXMLInfrastuctureModule
  @brief The public fields within the RTIXMLContext
*/
struct RTIXMLContextPublicFields {
    /*e
      \brief This member is used to signal an error condition during the parsing
      process.
    */
    RTIBool error;
    /*e
      \brief This member is a read-only and provides the current parsing depth.

      The root of the XML document has depth 1
    */
    int depth;

    /*e
     * \brief the current line number of the file. It allows override the values
     * provided by expat
    */
    int currentFileOffset;

    /*e
     * \brief the line number offset for the current file context. It allows
     * override the values provided by expat
     */
    int currentFileGlobalOffset;

    /*e
      \brief User data. It makes it possible to pass information among
      extensions from different families
    */
    void *userData;

    /*
     * The following enum stores the format used by the byteData type when
     * it contains only two digits. This is required because if not we cannot
     * distinguish if the base is HEX or Decimal.
     */
    RTIXMLByteBase byteDataBase;
};

#define RTIXMLContextPublicFields_INITIALIZER \
    { \
        RTI_FALSE,                     /* error */ \
                0,                     /* depth */ \
                0,                     /* currentFileOffset */ \
                0,                     /* currentFileGlobalOffset */ \
                NULL,                  /* userData */ \
                RTI_XML_BYTE_BASE_NONE /* byteDataBase */ \
    }

/*e \ingroup RTIXMLInfrastuctureModule
  @brief The RTIXMLContext is used to provide information about the parsing
  process
*/
struct RTIXMLContext {
    struct XML_ParserStruct **parser;

    /*e
      \brief Public fields. Available to public functions such as onEndTag.
    */
    struct RTIXMLContextPublicFields publicFields;

    /*e
      \brief error kind. This must be the last field. It cannot be exposed to
     * to the user
    */
    RTIXMLErrorKind errorKind;
};

#define RTIXMLContext_INITIALIZER \
    { \
        NULL, /* parser */ \
                RTIXMLContextPublicFields_INITIALIZER, \
                RTI_XML_NO_ERROR /* errorKind \
                                  */ \
    }

/*e \ingroup RTIXMLInfrastuctureModule
  @brief The RTIXMLPublicContext is what is exposed to user functions such as
  onEndTag.
*/
struct RTIXMLPublicContext {
    /*e
       \brief Opaque data that should not be touched
    */
    void *_parser;

    /*e
      \brief Public fields
    */
    struct RTIXMLContextPublicFields publicFields;
};

#define RTIXMLPublicContext_INITIALIZER \
    { \
        NULL, /* _parser */ \
                RTIXMLContextPublicFields_INITIALIZER \
    }

/*i \ingroup RTIXMLInfrastructureModule
  @brief RTIXMLSaveContext controls how objects are saved
*/
struct RTIXMLSaveContext {
    /*e
      \brief Destination output file
    */
    FILE *fout;
    /*e
      \brief Destination output string
    */
    char *sout;
    /*e
      \brief Size allocated for sout
    */
    unsigned int ssize;
    /*e
      \brief Number of characters printed on either fout or sout (not including
      the trailing '\0' used to end output to strings)
     */
    unsigned int outputStringLength;
    /*e
      \brief This member controls the indent depth
    */
    int depth;
    /*e
      \brief This member is used to signal an error condition during the parsing process.
    */
    RTIBool error;
    /*e
      \brief This member is availabler for higher levels to store information
    */
    void *userData;
};


#define RTIXMLSaveContext_INITIALIZER {  \
    NULL,                                \
    NULL,                                \
    0,                                   \
    0,                                   \
    0,                                   \
    RTI_FALSE,                           \
    NULL                                 \
}

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

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Sets the current line state
*/
extern RTIXMLDllExport
void RTIXMLContext_setContextLineNumber(struct RTIXMLContext * context, int line);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Reset the current line state
*/
extern RTIXMLDllExport
void RTIXMLContext_resetContextLineNumber(struct RTIXMLContext * context);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Returns the current line number of the parser. The first line is reported as 1.
*/
extern RTIXMLDllExport
int RTIXMLContext_getCurrentLineNumber(struct RTIXMLContext * context);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Gets the number of attributes
*/
extern RTIXMLDllExport
int RTIXMLHelper_getAttributeCount(const char **attrList);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Gets the value of an attribute given its name
*/
extern RTIXMLDllExport
const char * RTIXMLHelper_getAttribute(const char **attrList,const char * name);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Removes leading and trailing white space from the supplied string.
*/
extern RTIXMLDllExport
const char * RTIXMLHelper_strTrim(char * str);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Handles the passed string, saving it to a RTIXMLSaveContext structure.

  If a valid file has been supplied, the string is printed to the file.
  If a buffer has been supplied the string will be added to the buffer
  (provded there is space - if there is no space in the buffer the required
  length is updated). If no buffer nor file is supplied, the required size of
  the buffer is updated.

  @pre self is not NULL

  @param self \b In. Pointer to save context.
  @param format \b In. String to handle (variadic).
*/
extern RTIXMLDllExport
void RTIXMLSaveContext_freeform(
    struct RTIXMLSaveContext * self,
    const char *format, ...);

extern RTIXMLDllExport
void RTIXMLSaveContext_freeform_v(
    struct RTIXMLSaveContext *self,
    const char *format,
    va_list args,
    va_list argsAux);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Saves indent in a RTIXMLSaveContext structure.

  @pre self is not NULL

  @param self \b In. Pointer to save context
*/
extern	RTIXMLDllExport void RTIXMLSaveContext_indent(struct RTIXMLSaveContext * self);

/*e \ingroup RTIXMLInfrastuctureModule
 * @brief Appends a string to the save context.
 *
 * If exporting to string, if the string is too long to fit in the buffer, it
 * will not be appended and the function will just update the output string
 * length.
 * If exporting to file, it will write the string to the file.
 * It is allowed to call this function with both a NULL string and NULL file, in
 * which case it will just update the output string length.
 * If an error happens, it will set the error flag to RTI_TRUE.
 *
 * @pre self is not NULL.
 * @pre str is not NULL and points to a zero-terminated string.
 *
 * @param self \b In/Out. Pointer to save context
 * @param str \b In. String to append
 */
extern RTIXMLDllExport void RTIXMLSaveContext_appendString(
        struct RTIXMLSaveContext *self,
        const char *str);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Initializes RTIXMLSaveContext structure

  @pre self is not NULL

  @param self \b In. Pointer to save context
*/
extern	RTIXMLDllExport RTIBool RTIXMLSaveContext_initialize(struct RTIXMLSaveContext * self);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Finalizes RTIXMLSaveContext structure

  @pre self is not NULL

  @param self \b In. Pointer to save context
*/
extern	RTIXMLDllExport RTIBool RTIXMLSaveContext_finalize(struct RTIXMLSaveContext * self);

/*e \ingroup RTIXMLInfrastuctureModule
  @brief Definition of an XML name-value property
 */
struct RTIXMLProperty {
    char *name;
    char *value;
};


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

#endif /* rtixml_infrastructure_h */