/////////////////////////////////////////////////////////////////////////////// 
// 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_ODMVDXMLTEMPLATEREF_H_INCLUDED_)
#define ODA_ODMVDXMLTEMPLATEREF_H_INCLUDED_

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

#include "IfcEntity.h"
#include "MvdXmlElement.h"
#include "MvdXmlConceptTemplate.h"

/** \details 
Contains declarations related to Model View Definition (MVD) functionality.
*/
namespace OdMvdXml
{
  SMARTPTR(OdMvdXmlTemplateRef);

  /** \details 
    A class that implements a reference to an MVDXML Concept Template.
  */
  class MVDXML_EXPORT OdMvdXmlTemplateRef : public OdMvdXmlElement
  {
    ODRX_DECLARE_MEMBERS(OdMvdXmlTemplateRef);

  public:
    /** \details 
      Retrieves the reference to the Concept Template (by @ref). 
      The Concept Template reference is represented with a unique identifier when it may be defined within the same file.
      \returns An <exref target="../tkernel_api_cpp/OdGUID.html">OdGUID</exref> object that represents the reference to the Concept Template.
      \remarks 
      The <exref target="../tkernel_api_cpp/OdGUID.html">OdGUID</exref> object returned by the method is read-only (the object is returned as a C++ constant reference). 
    */
    const OdGUID& getRef() const;
    
    /** \details 
      Retrieves the external reference to the Concept Template (by @href).
      The external reference refers to a Concept Template from an external file. 
      \returns An <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI string</exref> that contains the external reference. 
      \remarks 
      The external reference (by @href) is reserved for future usage.
    */
    const OdAnsiString& getHref() const;
    
    /** \details 
      Sets the external reference to the Concept Template (by @href).
      The external reference refers to a Concept Template from an external file.
      \param value [in] An <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI string</exref> that contains the external reference.
      \remarks 
      The external reference (by @href) is reserved for future usage.
    */
    void setHref(const OdAnsiString& value);
    
    /** \details 
      Retrieves the identifier prefix for the Concept Template reference.
      IdPrefix prevents ambiguous identification, in cases when the same part of template is referenced twice in a Concept Template tree.
      \returns An <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI string</exref> that contains the identifier prefix. 
    */
    const OdAnsiString& getIdPrefix() const;
    
    /** \details 
      Sets the identifier prefix for the Concept Template reference.
      IdPrefix prevents ambiguous identification, in cases when the same part of template is referenced twice in a Concept Template tree.
      \param value [in] An <exref target="../tkernel_api_cpp/OdAnsiString.html">ANSI string</exref> that contains the identifier prefix.
    */
    void setIdPrefix(const OdAnsiString& value);
    
    /** \details 
      Retrieves the empty flag for the Concept Template reference. 
      The empty flag determines whether the Concept Template reference is empty (equals true) or not (equals false).
      \returns true if the Concept Template reference is empty; otherwise, the method returns false.
    */
    const bool isEmpty() const;
    
    /** \details 
      Retrieves whether the Concept Template reference is external. 
      The external reference (by @href) refers to a Concept Template from an external file.
      \returns true if the Concept Template reference is external; otherwise, the method returns false.
    */
    const bool isExternalLink() const;

    /** \details 
      Retrieves an <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAttributeRule.html">attribute rule</exref> by its identifier.
      \param ruleId [in] An ANSI (null-terminated) string that contains the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAttributeRule.html">attribute rule</exref> identifier.
      \returns 
      A raw pointer to an <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAttributeRule.html">OdMvdXmlAttributeRule</exref> object. 
      If no <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlAttributeRule.html">attribute rules</exref> with the specified identifier are found, the method returns the NULL pointer.
    */
    OdMvdXmlAttributeRule* getAttributeRuleByID(const char* ruleId);
    
    /** \details 
      Retrieves an <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlEntityRule.html">entity rule</exref> by its identifier.
      \param ruleId [in] An ANSI (null-terminated) string that contains the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlEntityRule.html">entity rule</exref> identifier.
      \returns 
      A raw pointer to an <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlEntityRule.html">OdMvdXmlEntityRule</exref> object. 
      If no <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlEntityRule.html">entity rules</exref> with the specified identifier are found, the method returns the NULL pointer.
    */
    OdMvdXmlEntityRule* getEntityRuleByID(const char* ruleId);
    
    /** \details 
      Retrieves an <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlEntityRule.html">entity rules</exref> by its identifier.
      \param ruleId [in] An ANSI (null-terminated) string that contains the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlEntityRule.html">entity rule</exref> identifier.
      \returns 
      A raw pointer to an <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlEntityRule.html">OdMvdXmlEntityRule</exref> object. 
      If no <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlEntityRule.html">entity rules</exref> with the specified identifier are found, the method returns the NULL pointer.
    */
    OdMvdXmlRule* getRuleByID(const char* ruleId);

    /** \details
      Checks whether a specified <exref target="../tifc_api_cpp/OdDAI__ApplicationInstance.html">ApplicationInstance</exref> meets all constraints defined within the exchange requirements.
      \param pInstance [in] A raw pointer to the <exref target="../tifc_api_cpp/OdDAI__ApplicationInstance.html">application instance</exref> to check up.
      \param result    [out] A placeholder for the checkup result, represented with a boolean value.
      \returns eOk if the instance was successfully checked; otherwise, the method returns an appropriate error code.
      \remarks 
      If any of the required data is missing or violates any of the constraints, the checkup fails, and the output result parameter value equals false.
      If the checkup procedure fails itself, the value of the output parameter with the checkup result has an undefined value.
    */
    OdResult checkInstance(const OdDAI::ApplicationInstance* pInstance, bool& result);

    /** \details
      Cleans the entities assigned to the Entity Rules.
     */
    void cleanInstance();

    /** \details
      The assignment operator for Concept Template reference.
      \param other [in] Another <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlTemplateRef.html">OdMvdXmlTemplateRef</exref> object to be assigned (right-hand operand of the assigment operation).
      \returns The Concept Template reference object modified by the assigment operation.
    */
    OdMvdXmlTemplateRef& operator=(const OdMvdXmlTemplateRef& other);

  protected:
    /** \details
      Copy data from the other element.

      \param other [in] Object to copy from.
    */
    void assign(const OdMvdXmlTemplateRef* other);

    /** \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
      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;

  private:
    /** \details
      Mandatory reference to the ConceptTemplate by uuid, where such 
      template may be defined within the same file.
    */
    OdGUID m_ref;
    
    /** \details
      Mandatory reference to the ConceptTemplate by uuid, where template defined on external file.

    \remarks
      Current usage of mvdXML imposes the inclusion off all concept
      templates within the same data file. The external reference by @href is
      reserved for future usage.
    */
    OdAnsiString m_href;
    
    /** \details
      IdPrefix - an optional prefix for the RuleId name, used to prevent ambiguous RuleId,
      if the same partial template is referenced twice in a concept template tree.
    */
    OdAnsiString m_idPrefix;

    /** \details
      Reference to the OdMvdXmlConceptTemplate class.
    */
    OdMvdXmlConceptTemplatePtr m_template;
  };
}

#endif // !defined(ODA_ODMVDXMLTEMPLATEREF_H_INCLUDED_)