/*
 * Copyright (c) 2005-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_extension_h
#define rtixml_extension_h


/* ---------------------------------------------------------------------- */
/* EXTENSION CLASS ------------------------------------------------------ */
/* ---------------------------------------------------------------------- */

/*e \file
    \brief Extension class API.
*/

/*e \defgroup RTIXMLExtensionClass RTIXMLExtensionClass
  \ingroup RTIXMLModule
  \brief The extension classes are used to create XML objects.

  Each extension class is associated to a XML tag and they
  must be registered with the parser.
*/

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

#include "rtixml/rtixml_dll.h"
#include "rtixml/rtixml_infrastructure.h"
#include "rtixml/rtixml_object.h"

#ifdef __cplusplus
    extern "C" {
#endif

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

struct RTIXMLExtensionClass;

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

/*e \ingroup RTIXMLExtensionClass

  \brief Function called when a new start tag is found inside
  the element associated to the extension class of the input object

  @pre self is not NULL.
  @pre tagName is not NULL.
  @pre context is not NULL.

  @param self \b In. Pointer to the XML object.
  @param tagName \b In. Tag name.
  @param attr \b In. List of attributes associated to the start tag.
  <br>Each attribute seen in a start (or empty) tag occupies 2 consecutive
  places in this vector: the attribute name followed by the attribute value.
  These pairs are terminated by a null pointer.
  @param context \b InOut. Pointer to the XML context.

  @return If there is an error, context->error must be set to
  RTI_TRUE
 */
typedef void (*RTIXMLExtensionClassOnStartTagFunction)(
        struct RTIXMLObject *self,
        const char *tagName,
        const char **attr,
        struct RTIXMLPublicContext *context);

/*e \ingroup RTIXMLExtensionClass

  \brief Function called when a new end tag is found inside
  the element associated to the extension class of the input object.

  @pre self is not NULL.
  @pre tagName is not NULL.
  @pre elementText is not NULL.
  @pre context is not NULL.

  @param self \b In. Pointer to the object.
  @param tagName \b In. Tag name.
  @param elementText \b In. The element text.
  @param context \b InOut. Pointer to the XML context.

  @return If there is an error, context->error must be set to
  RTI_TRUE
 */
typedef void (*RTIXMLExtensionClassOnEndTagFunction)(
        struct RTIXMLObject *self,
        const char *tagName,
        const char *elementText,
        struct RTIXMLPublicContext *context);


/*e \ingroup RTIXMLExtensionClass

  \brief Function used to create a new XML object.

  That object must inherits from RTIXMLObject.

  @pre extensionClass is not NULL.
  @pre attr is not NULL.
  @pre context is not NULL.

  @param extensionClass \b In. Extension class of the new object.
  @param parentObject \b In. Pointer to the parent object.
  @param attr \b The XML attributes associated to the objedt that is going to be
  created.<br> Each attribute seen in a start (or empty) tag occupies 2
  consecutive places in this vector: the attribute name followed by the
  attribute value. These pairs are terminated by a null pointer.

  @return The new RTIXMLObject if success. Otherwise, NULL.
 */
typedef struct RTIXMLObject *(*RTIXMLExtensionClassNewObjectFunction)(
        const struct RTIXMLExtensionClass *extensionClass,
        const struct RTIXMLObject *parentObject,
        const char **attr,
        struct RTIXMLPublicContext *context);

/*e \ingroup RTIXMLExtensionClass
  \brief Function used to delete an extension class object

  @pre self is not NULL

  @param self \b In. Pointer to the object to be deleted.
 */
typedef void (*RTIXMLExtensionClassDeleteObjectFunction)(
        struct RTIXMLObject *self);

/*e \ingroup RTIXMLExtensionClass
  \brief Function used to delete an extension class object

  @pre self is not NULL

  @param self \b In. Pointer to the object to be deleted.
 */
typedef void (*RTIXMLExtensionClassSaveObjectFunction)(
        struct RTIXMLObject *self,
        struct RTIXMLSaveContext *dst);

/*e \ingroup RTIXMLExtensionClass

  \brief Gets the tag name associated to the input RTIXMLExtensionClass

  @pre self is not NULL

  @param self \b In. Pointer to the RTIXMLExtensionClass.
*/
extern RTIXMLDllExport const char * RTIXMLExtensionClass_getTagName(
        const struct RTIXMLExtensionClass *self);

/*e \ingroup RTIXMLExtensionClass

  \brief Gets the user data associated to the input RTIXMLExtensionClass

  @pre self is not NULL

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

  @return userData
*/
extern RTIXMLDllExport void * RTIXMLExtensionClass_getUserData(
        struct RTIXMLExtensionClass *self);


/*e \ingroup RTIXMLExtensionClass
  @brief Creates a new RTIXMLExtensionClass

  @pre tagName is not NULL.
  @pre onStartTagFcn is not NULL.
  @pre onEndTagFcn is not NULL.
  @pre newObjectFcn is not NULL.
  @pre deleteObjectFcn is not NULL.

  @param tagName \b In. Name of the tag associated to the extension class.
  @param userData \b In. User data.
  @param allowDuplicatedObjects \b In. Indicates if duplicated objects (objects
  with the same fully qualified name) are allowed for the extension class.
  @param defaultName \b In. Defines the behavior if the name attribute for the
  extension class object is not specified. If NULL, then we give the object a
  unique name using a counter value. If non-NULL, then we give the object the
  defaultName.
  @param onStartTagFcn \b In. Function that will be called when a start tag is
  found within the element associated to a class object.
  @param onEndTagFcn \b In. Function that will be called when an end tag is
  found within the element associated to a class object.
  @param newObjectFcn \b In. Function that will be called to create a new XML
  object.
  @param deleteObjectFcn \b In. Function that will be called to delete an
  existing XML object.

  @return A pointer to the new RTIXMLExtensionClass if success. Otherwise, NULL.
*/
extern RTIXMLDllExport struct RTIXMLExtensionClass *RTIXMLExtensionClass_new(
        const char *tagName,
        void *userData,
        RTIBool allowDuplicatedObjects,
        RTIBool isRoot,
        const char *defaultName,
        RTIXMLExtensionClassOnStartTagFunction onStartTagFcn,
        RTIXMLExtensionClassOnEndTagFunction onEndTagFcn,
        RTIXMLExtensionClassNewObjectFunction newObjectFcn,
        RTIXMLExtensionClassDeleteObjectFunction deleteObjectFcn,
        RTIXMLExtensionClassSaveObjectFunction saveObjectFcn);

/*e \ingroup RTIXMLExtensionClass
  @brief Deletes an extension class

  @pre self is not NULL

  @param self \b In. Pointer to the RTIXMLExtensionClass extension to be
  deleted.
*/
extern RTIXMLDllExport void RTIXMLExtensionClass_delete(
        struct RTIXMLExtensionClass *self);

/*e \ingroup RTIXMLExtensionClass
  @brief Finalizes the input DDSXMlExtensionClass.

  @param self \b In. Pointer to the RTIXMLExtensionClass extension to be
  finalized.
*/
extern RTIXMLDllExport void RTIXMLExtensionClass_finalize(
        struct RTIXMLExtensionClass *self);

/*e \ingroup RTIXMLExtensionClass
  @brief Initializes the input RTIXMLExtensionClass.

  @pre self is not NULL.
  @pre tagName is not NULL.
  @pre onStartTagFcn is not NULL.
  @pre onEndTagFcn is not NULL.
  @pre newObjectFcn is not NULL.
  @pre deleteObjectFcn is not NULL.

  @param self \b In. Pointer to the RTIXMLExtensionClass to be initialized.
  @param tagName \b In. Name of the tag associated to the extension class.
  @param allowDuplicatedObjects \b In. Indicates if duplicated objects are
  allowed for the extension class.
  @param userData \b In. User data.
  @param defaultName \b In. Defines the behavior if the name attribute for the
  extension class object is not specified. If NULL, then we give the object a
  unique name using a counter value. If non-NULL, then we give the object the
  defaultName.
  @param onStartTagFcn \b In. Function that will be called when a start tag is
  found within the element associated to a class object.
  @param onEndTagFcn \b In. Function that will be called when an end tag is
  found within the element associated to a class object.
  @param newObjectFcn \b In. Function that will be called to create a new XML
  object.
  @param deleteObjectFcn \b In. Function that will be called to delete an
  existing XML object.

  @return RTI_TRUE if success. Otherwise, RTI_FALSE
*/
extern RTIXMLDllExport RTIBool RTIXMLExtensionClass_initialize(
        struct RTIXMLExtensionClass *self,
        const char *tagName,
        void *userData,
        RTIBool allowDuplicatedObjects,
        RTIBool isRoot,
        const char *defaultName,
        RTIXMLExtensionClassOnStartTagFunction onStartTagFcn,
        RTIXMLExtensionClassOnEndTagFunction onEndTagFcn,
        RTIXMLExtensionClassNewObjectFunction newObjectFcn,
        RTIXMLExtensionClassDeleteObjectFunction deleteObjectFcn,
        RTIXMLExtensionClassSaveObjectFunction saveObjectFcn);


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

#endif /* rtixml_extension_h */