/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

#if !defined(ODA_ODMVDXMLROOT_H_INCLUDED_)
#define ODA_ODMVDXMLROOT_H_INCLUDED_

#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000

#include "MvdXmlIdentity.h"
#include "MvdXmlConceptTemplate.h"
#include "MvdXmlModelView.h"
#include "MvdXmlAuditInfo.h"

/** \details 
Contains declarations related to Model View Definition (MVD) functionality.
*/
namespace OdMvdXml
{
  /** \details
    Declarations of the mvdXML format versions.
  */
  enum mvdXmlVersion
  {
    /** Version is unset. */
    mvdXmlUnset,
    
    /** mvdXML format version 1.1. */
    mvdXml1dot1,
    
    /** mvdXML format version 1.2. */
    mvdXml1dot2,
    
    /** mvdXML format version 1-1. */
    mvdXml1_1
  };

  SMARTPTR(OdMvdXmlRoot);

  /** \details 
    A class that implements the Root element of a MVDXML document. 
  */
  class MVDXML_EXPORT OdMvdXmlRoot : public OdMvdXmlIdentity
  {
    ODRX_DECLARE_MEMBERS(OdMvdXmlRoot);

  public:
    /** \details 
      Creates a new Root element with default parameters.
    */
    OdMvdXmlRoot();

    /** \details
      Adds an element to the array of elements referenced by the Root element.
      \param pElement [in] A smart pointer to the new element represented with an instance of the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlIdentity.html">OdMvdXmlIdentity</exref> class.
    */
    void addElement(OdMvdXmlIdentityPtr pElement);
    
    /** \details 
      Loads the content of a specified mvdXML document and makes the Root object the root node of the loaded document content.
      \param pDocument [in] A raw pointer to the document object. 
      \param audit     [out] A placeholder for storing the audit information, represented with a raw pointer to an <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAuditInfo.html">OdMvdXmlAuditInfo</exref> object.
      \returns eOk if the document was successfully loaded; otherwise, the method returns an appropriate error code.
    */
    OdResult loadDocument(TiXmlDocument* pDocument, OdMvdXmlAuditInfo* audit);
    
    /** \details 
      Saves the content referenced by the Root element in a specified mvdXML document.
      \param pDocument [in] A raw pointer to the document object. 
      \param audit     [out] A placeholder for storing the audit information, represented with a raw pointer to an <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAuditInfo.html">OdMvdXmlAuditInfo</exref> object.
      \returns eOk if the document was successfully saved; otherwise, the method returns an appropriate error code.
    */
    OdResult saveDocument(TiXmlDocument* pDocument, OdMvdXmlAuditInfo* audit);
    
    /** \details 
      Retrieves a child element with a specified identifier. 
      \param uuid [in] An <exref target="../tkernel_api_cpp/OdGUID.html">OdGUID</exref> object that contains the element's identifier.
      \returns A smart pointer to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlIdentity.html">OdMvdXmlIdentity</exref> object. If no element with the specified identifier found, the method returns an NULL pointer.
    */
    OdMvdXmlIdentityPtr getElement(const OdGUID& uuid) const;
    
    /** \details 
      Retrieves the list of <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlModelView.html">OdMvdXmlModelView</exref> within the document represented with the Root element.
      \returns An array of smart pointers to <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlModelView.html">OdMvdXmlModelView</exref> objects.
    */
    const OdMvdXmlModelViewPtrArray& getViews() const;
    
    /** \details 
      Retrieves the list of <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlConceptTemplate.html">Concept Templates</exref> assigned with the Root element. 
      \returns An array of smart pointers to <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlConceptTemplate.html">OdMvdXmlConceptTemplate</exref> objects.
    */
    const OdMvdXmlConceptTemplatePtrArray& getTemplates() const;
    
    /** \details 
      Appends a new Concept Template to the Root element. 
      \param item [in] A smart pointer to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlConceptTemplate.html">OdMvdXmlConceptTemplate</exref> object to be added.
      \returns An unsigned integer value that contains the index of the appended element. If the append operation failed, the method returns -1.
    */
    int appendTemplate(OdMvdXmlConceptTemplatePtr item);
    
    /** \details 
      Retrieves the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAuditInfo.html">audit object</exref> for the Root element. 
      \returns A raw pointer to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAuditInfo.html">OdMvdXmlAuditInfo</exref> object. 
    */
    OdMvdXmlAuditInfo* getAudit();
    
    /** \details 
      Sets a new <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAuditInfo.html">audit object</exref> for the Root element. 
      \param value [in] A raw pointer to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAuditInfo.html">OdMvdXmlAuditInfo</exref> object. 
    */
    void setAudit(OdMvdXmlAuditInfo* value);
    
    /** \details 
      Retrieves the XML namespace attribute of the Root element.
      \returns An <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI string</exref> that contains the value of the XML namespace attribute.
    */
    OdAnsiString getXmlns();
    
    /** \details 
      Sets the XML namespace attribute of the Root element.
      \param value [in] An <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI string</exref> that contains the value of the XML namespace attribute.
    */
    void setXmlns(const OdAnsiString& value);
    
    /** \details 
      Retrieves the XML namespace standard prefix for the Root element.
      \returns An <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI string</exref> that contains the value of the XML namespace prefix.
    */
    OdAnsiString getXsi();
    
    /** \details 
      Sets the XML namespace standard prefix of the Root element.
      \param value [in] An <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI string</exref> that contains the value of the XML namespace prefix.
    */
    void setXsi(const OdAnsiString& value);
    
    /** \details 
      Retrieves the XML schema file location for the Root element. 
      \returns 
      An <exref target="../tkernel_api_cpp/OdArray@classT@classA__OdArray@const_OdArray_.html">array</exref> 
      of <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI strings</exref>. 
      Each element contains a pair &quot;namespace&quot; - &quot;schema file location&quot;.
    */
    OdAnsiStringArray& getSchemaLocation();
    
    /** \details 
      Sets the XML schema file location for the Root element.
      \param value [in] An <exref target="../tkernel_api_cpp/OdArray@classT@classA__OdArray@const_OdArray_.html">array</exref> 
                        of <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI strings</exref>. 
                        Each element contains a pair &quot;namespace&quot; - &quot;schema file location&quot;.
    */
    void setSchemaLocation(const OdAnsiStringArray& value);

    /** \details
      Retrieves the version of the Root element.
      \returns An <exref target="../tifc_api_cpp/OdMvdXml__mvdXmlVersion.html">mvdXmlVersion</exref> value that contains the version of the Root element.
    */
    const mvdXmlVersion getVersion() const;

    /** \details
      Clears the Root element.
    */
    void Clear();

  protected:

    /** \details
      Retrieves the name of the element. This name is used to write the element to a file.

      \returns The name of the element.
    */
    virtual OdAnsiString getElementName();

    /** \details
      Reads attributes from a xml element.

      \param pItem [in] Pointer to a xml element containing attributes.

      \returns eOk if the data was successfully read; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult inAttributes(TiXmlElement* pItem) override;

    /** \details
      Reads child element from a xml element.

      \param nodeName [in] The node name of the xml element containing the child data.
      \param pChild [in] Pointer to a xml element containing child data.

      \returns eOk if the data was successfully read; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult inChildNode(const char *nodeName, TiXmlElement* pChild) override;

    /** \details
      Writing attributes to the xml element.

      \param pItem [in] Pointer to the xml element to which you want to add attributes.

      \returns eOk if the data was written successfully; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult outAttributes(TiXmlElement* pItem) override;

    /** \details
      Writing child elements to the xml element.

      \param pParent [in] Pointer to the xml element to which you want to add children.

      \returns eOk if the data was written successfully; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult outChildNodes(TiXmlNode* pParent) override;

  private:

    /** \details
      Set of templates, which may be exchanged with or without referencing model 
      view definitions.
    */
    OdMvdXmlConceptTemplatePtrArray m_templates;

    /** \details
      List of model view definitions, in order of listing in generated documentation.
      
      \remarks
      If empty, the mvdXML file is only used to exchange concept templates
      and cannot be used to fulfill other purposes such as data validation
    */
    OdMvdXmlModelViewPtrArray       m_views;

    /** \details
      List of identification elements. Used to search for items by their uuid.
    */
    OdMvdXmlIdentityPtrArray        m_elements;

    /** \details
      Pointer to an AuditInfo element. Used for logging.
    */
    OdMvdXmlAuditInfo*              m_audit;

    /*
     TODO Do I need to keep these values?
    */
    OdAnsiString                    m_xmlns;
    OdAnsiString                    m_xsi;
    OdAnsiStringArray               m_schemaLocation;
  };
}

#endif // !defined(ODA_ODMVDXMLROOT_H_INCLUDED_)