///////////////////////////////////////////////////////////////////////////////
// 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.
///////////////////////////////////////////////////////////////////////////////

#ifndef _PRCFILESTRUCTURE_INCLUDED_
#define _PRCFILESTRUCTURE_INCLUDED_ 
 

#include "PrcSchema.h"
#include "PrcFileStructureGlobals.h"
#include "PrcFileStructureTree.h"
#include "PrcFileStructureTessellation.h"
#include "PrcFileStructureGeometry.h"
#include "PrcUncompressedFiles.h"

class OdPrcHandleTree;
class OdPrcStub;
class OdPrcFileStructureImpl;

SMARTPTR(OdPrcFileStructure);

/** \details 
Class implements storing and handling information about a PRC file structure.
Each PRC file structure consists of the following parts:
<table>
Component           Description
Header              Contains common information about the file structure.
Schema              Contains information about entities that have been changed between the minimum format version for reading and original author format version. 
Tree of items       Description of the items tree. Each item can be a product occurrence, a part definition, a representation item, or a markup.
Tessellation data   Contains tessellated data in the leaf items of the structure tree.
Global data         Coordinate systems, colors, linestyles, and other file structures referenced in this file structure.
Exact geometry      Exact geometry and topology data of the leaf items of the structure tree.
Extra geometry      Geometry summary information that can be loaded partially without loading all the geometry.
</table>
<group PRC_Files_Structures_Assemblies>
*/
class PRC_TOOLKIT OdPrcFileStructure : public OdDbBaseDatabase
{
private:
  friend class OdPrcSystemInternals;
  OdPrcFileStructureImpl *m_pImpl;

public:
  //DOM-IGNORE-BEGIN
  ODPRCRX_DECLARE(OdPrcFileStructure);
  //DOM-IGNORE-END

  /** \details
  Requests the current exact geometry of the file structure.
  \returns An <link OdPrcFileStructureGeometry, OdPrcFileStructureGeometry> object that contains the geometry from the file structure.
  \remarks 
  The method returns the exact geometry via a reference to an <link OdPrcFileStructureGeometry, OdPrcFileStructureGeometry> object; 
  therefore, any modification affects the file structure object and can be used to set new exact geometry for it.
  */
  OdPrcFileStructureGeometry &fileStructureGeometry();
  
  /** \details 
  Requests the current exact geometry of the file structure.
  \returns A constant reference to the <link OdPrcFileStructureGeometry, OdPrcFileStructureGeometry> object that contains the geometry from the file structure.
  \remarks 
  Call this method to restrict modifications of the returned <link OdPrcFileStructureGeometry, OdPrcFileStructureGeometry> object outside the file structure object.
  */
  const OdPrcFileStructureGeometry &fileStructureGeometry() const;
  
  /** \details
  Requests the current tessellation data from the file structure.
  \returns An <link OdPrcFileStructureTessellation, OdPrcFileStructureTessellation> object that contains the tessellation data from the file structure.
  \remarks 
  The method returns the tessellation data via a reference to the <link OdPrcFileStructureTessellation, OdPrcFileStructureTessellation> object; 
  therefore, any modification of the returned tessellation data affects the file structure object and can be used to set new tessellation data for it.
  */
  OdPrcFileStructureTessellation &fileStructureTessellation();
  
  /** \details 
  Requests the current tessellation data from the file structure. 
  \returns A constant reference to the <link OdPrcFileStructureTessellation, OdPrcFileStructureTessellation> object that contains the tessellation data from the file structure.
  \remarks 
  Call this method to restrict modifications of the returned <link OdPrcFileStructureTessellation, OdPrcFileStructureTessellation> object outside the file structure object.
  */
  const OdPrcFileStructureTessellation &fileStructureTessellation() const;
  
  /** \details
  Requests the current file structure tree.
  \returns An <link OdPrcFileStructureTree, OdPrcFileStructureTree> object. 
  \remarks 
  The method returns the <link OdPrcFileStructureTree, OdPrcFileStructureTree> object of the file structure via a reference; 
  therefore, any modification of the returned <link OdPrcFileStructureTree, OdPrcFileStructureTree> object affects the file structure object 
  and can be used to set a new <link OdPrcFileStructureTree, file structure tree>. 
  */
  OdPrcFileStructureTree &fileStructureTree();
  
  /** \details 
  Requests the current file structure tree.
  \returns A constant reference to the <link OdPrcFileStructureTree, OdPrcFileStructureTree> object.
  \remarks 
  Call this method if you want to restrict modifications of the returned <link OdPrcFileStructureTree, file structure tree> object outside the file structure object.
  */
  const OdPrcFileStructureTree &fileStructureTree() const;
  
  /** \details
  Requests the current <link OdPrcFileStructureGlobals, global data> of the file structure.
  \returns An <link OdPrcFileStructureGlobals, OdPrcFileStructureGlobals> object. 
  \remarks 
  The method returns the <link OdPrcFileStructureGlobals, OdPrcFileStructureGlobals> object of the file structure via a reference; 
  therefore, any modification of the returned <link OdPrcFileStructureGlobals, OdPrcFileStructureGlobals> object affects the file structure object 
  and can be used to set a new <link OdPrcFileStructureGlobals, global data>. 
  */
  OdPrcFileStructureGlobals &fileStructureGlobals();
  
  /** \details 
  Requests the current <link OdPrcFileStructureGlobals, global data> of the file structure.
  \returns A constant reference to the <link OdPrcFileStructureGlobals, OdPrcFileStructureGlobals> object.
  \remarks 
  Call this method if you want to restrict modifications of the returned <link OdPrcFileStructureGlobals, global data> object outside the file structure object.
  */
  const OdPrcFileStructureGlobals &fileStructureGlobals() const;
  
  /** \details
  Requests the current <link OdPrcSchema, schema> of the file structure.
  \returns An <link OdPrcSchema, OdPrcSchema> object. 
  \remarks 
  The method returns the <link OdPrcSchema, OdPrcSchema> object of the file structure via a reference; 
  therefore, any modification of the returned <link OdPrcSchema, OdPrcSchema> object affects the file structure object 
  and can be used to set a new <link OdPrcSchema, schema>.
  */
  OdPrcSchema &schema();
  
  /** \details 
  Requests the current <link OdPrcSchema, schema> of the file structure.
  \returns A constant reference to the <link OdPrcSchema, OdPrcSchema> object.
  \remarks 
  Call this method if you want to restrict modifications of the returned <link OdPrcSchema, schema> object outside the file structure object.
  */
  const OdPrcSchema &schema() const;

  /** \details 
  Requests the array of private <link OdPrcUncompressedFiles, uncompressed files> from the file structure header.
  \returns An <link OdPrcUncompressedFiles, OdPrcUncompressedFiles> object. 
  \remarks 
  The method returns the <link OdPrcUncompressedFiles, OdPrcUncompressedFiles> object of the file structure via a reference; 
  therefore, any modification of the returned <link OdPrcUncompressedFiles, OdPrcUncompressedFiles> object affects the file structure object 
  and can be used to set a new <link OdPrcUncompressedFiles, array of uncompressed files>.
  */
  OdPrcUncompressedFiles &uncompressedFiles();
  
  /** \details 
  Requests the array of <link OdPrcUncompressedFiles, uncompressed files> from the file structure header.
  \returns A constant reference to the <link OdPrcUncompressedFiles, OdPrcUncompressedFiles> object.
  \remarks 
  Call this method if you want to restrict modifications of the returned <link OdPrcUncompressedFiles, OdPrcUncompressedFiles> object outside the file structure object.
  */
  const OdPrcUncompressedFiles &uncompressedFiles() const;

  /** \details
  Requests the current unique identifier of the application.
  \returns An <link OdPrcUniqueId, OdPrcUniqueId> object that represents the unique identifier of the application.
  \remarks 
  The unique application identifier is returned as a reference to an <link OdPrcUniqueId, OdPrcUniqueId> object; 
  therefore, it can be used to set a new identifier.
  */
  OdPrcUniqueId &applicationId();
  
  /** \details
  Requests the current unique identifier of the application.
  \returns A constant reference to the <link OdPrcUniqueId, OdPrcUniqueId> object that represents the unique identifier of the application.
  \remarks 
  Call this method if you want to restrict modifications of the returned <link OdPrcUniqueId, OdPrcUniqueId> object.
  */
  const OdPrcUniqueId &applicationId() const;
  
  /** \details
  Returns the <link OdPrcUniqueId, unique identifier> of the file structure.
  \returns An <link OdPrcUniqueId, OdPrcUniqueId> object that represents the unique identifier of the file structure.
  \remarks 
  The method returns the <link OdPrcUniqueId, OdPrcUniqueId> object of the file structure via a reference; 
  therefore, any modification of the returned <link OdPrcUniqueId, OdPrcUniqueId> object affects the file structure object 
  and can be used to set a new <link OdPrcUniqueId, unique identifier>.
  */
  OdPrcUniqueId &fileStructureId();
  
  /** \details
  Requests the current unique identifier of the file structure.
  \returns A constant reference to the <link OdPrcUniqueId, OdPrcUniqueId> object that represents the unique identifier of the file structure.
  \remarks 
  Call this method if you want to restrict modifications of the returned <link OdPrcUniqueId, OdPrcUniqueId> object.
  */
  const OdPrcUniqueId &fileStructureId() const;
  
  /** \details
  Sets the required PRC format versions for reading and authoring data from the file structure.
  \param minimal_version_for_read [in] An unsigned 32-bit integer value that represents the minimum version for reading to be set.
  \param authoring_version        [in] An unsigned 32-bit integer value that represents the authoring version to be set.
  \returns The eOk value if new versions are successfully set, or an appropriate error code in the other case.
  */
  OdResult setVersions(OdUInt32 minimal_version_for_read, OdUInt32 authoring_version);
  
  /** \details
  Requests the minimum version of the PRC format required for reading data from the file structure.
  \returns An unsigned 32-bit integer value that contains the minimum version for reading.
  */
  OdUInt32 minimalVersionForRead() const;
  
  /** \details
  Requests the version of the authoring tool for working with the file structure.
  \returns An unsigned 32-bit integer value that contains the authoring version.
  */
  OdUInt32 authoringVersion() const;
  
  /** \details 
  Destroys the file structure object.
  */
  virtual ~OdPrcFileStructure();

  /** \details
  Adds a PRC object to the file structure.
  \param object [in] A pointer to the <link OdPrcReferencedBase, PRC object> to be added to the file structure.
  */
  void addObject (OdPrcReferencedBase *object);
  
  /** \details
  Adds a PRC object with a specified unique identifier to the file structure.
  \param object [in] A pointer to the <link OdPrcReferencedBase, PRC object> to be added to the file structure.
  \param uid    [in] An unsigned 32-bit integer value that contains the unique identifier of the object to be added.
  */
  void addObject (OdPrcReferencedBase *object, OdUInt32 uid);
  
  /** \details
  Adds a <link OdPrcBody, PRC body> to the file structure.
  \param body [in] A raw pointer to a <link OdPrcBody, PRC body> to be added to the file structure.
  */
  void addObject (OdPrcBody *body);
  
  /** \details
  Requests the <link OdPrcObjectId, PRC object identifier> for a file structure element specified with a specified handle.
  \param h [in] A database handle of the PRC object in the file structure.
  \returns The <link OdPrcObjectId, PRC object identifier> of the file structure element. 
  */
  OdPrcObjectId getObjectId (const OdDbHandle& h) const;

  /** \details
  Sets a new <link OdPrcObjectId, PRC object identifier> for the file structure.
  \param stub [in] A pointer to an OdDbStub object that represents the PRC object identifier.
  */
  void setObjectId (OdDbStub* stub);
  
  /** \details
  Requests the <link OdPrcObjectId, object identifier> of the file structure.
  \returns A constant reference to the <link OdPrcObjectId, OdPrcObjectId> instance. 
  \remarks 
  Since the method returns the file structure <link OdPrcObjectId, identifier> via a constant reference, it can't be modified outside the object.
  */
  const OdPrcObjectId& objectId() const;

  /** \details
  Writes extra geometry data from the file structure to a specified <link OdPrcCompressedFiler, output stream>.
  \param pStream [in] A pointer to the <link OdPrcCompressedFiler, output stream> to write to.
  */
  void writeExtraGeometry (OdPrcCompressedFiler *pStream);
  
  /** \details
  Reads extra geometry data from a specified <link OdPrcCompressedFiler, input stream> to the file structure.
  \param pStream [in] A pointer to the <link OdPrcCompressedFiler, input stream> to read from.
  */
  void readExtraGeometry (OdPrcCompressedFiler *pStream);

};

#endif // _PRCFILESTRUCTURE_INCLUDED_