///////////////////////////////////////////////////////////////////////////////
// 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 _PRCOBJECTID_
#define _PRCOBJECTID_

#include "DbHandle.h"
#include "SmartPtr.h"
#include "PrcToolkitExportDef.h"
#include "Gi/GiCommonDraw.h"

class OdDbStub;

class OdPrcStub;
class OdPrcBase;

/** \details 
A data type that represents a smart pointer to a <link OdPrcBase, PRC object>.
*/
typedef OdSmartPtr<OdPrcBase> OdPrcObjectPtr;

/** \details
Open mode enumerator. Determines the results of the open operation for a PRC object.
*/
enum OpenMode
{
  /** The object is not open.*/
  kNotOpen           = -1,  
  /** The object is open for reading.*/
  kForRead           = 0,   
  /** The object is open for reading and/or writing.*/
  kForWrite          = 1,   
  /** The object is open for notifications.*/
  kForNotify         = 2    
};

/** \details 
The class implements PRC object identifier (ID) functionality.
<group PRC_Datatypes_Classes> 
*/
class PRC_TOOLKIT OdPrcObjectId
{
public:
  
  /** \details
  Creates a PRC object identifier with a null value.
  */
  OdPrcObjectId() : m_Id (0) { }
  
  /** \details
  Creates a <link OdPrcObjectId, PRC object identifier> based on a specified stub.
  
  \param objectId [in] A raw pointer to the stub object.
  */
  OdPrcObjectId (OdDbStub* objectId) : m_Id (objectId) { }

  //PRC_TOOLKIT static const OdPrcObjectId kNull;

  /** \details
  Checks whether the PRC object identifier is empty (NULL).
  \return A Boolean value that is equal to true if the <link OdPrcObjectId, PRC object identifier> is empty (NULL); otherwise, the method returns false.
  */
  bool isNull() const     { return m_Id == 0; }

  /** \details
  Sets the <link OdPrcObjectId, PRC object identifier> to the NULL value.
  */
  void setNull()          { m_Id = 0; }

  /** \details
  Checks whether the PRC object identifier has a valid value.
  \return A Boolean value that is equal to true if the <link OdPrcObjectId, PRC object identifier> is valid; otherwise, the method returns false.
  */
  bool isValid() const;

  /** \details
  Checks whether the PRC object the identifier refers to is erased.
  \returns A Boolean value that is equal to true if the <link OdPrcObjectId, PRC object identifier> referred to is erased; otherwise, the method returns false.
  */
  bool isErased() const;

  /** \details
  An assignment operator for <link OdPrcObjectId, PRC object identifiers>. 
  Assigns the value of a specified <link OdPrcObjectId, PRC object identifier> to this <link OdPrcObjectId, PRC object identifier>.
  \param elementId [in] Another <link OdPrcObjectId, PRC object identifier> to assign (the right-hand operand of the assignment operation).
  \returns A reference to the <link OdPrcObjectId, PRC object identifier> modified by the assignment operation.
  */  
  OdPrcObjectId& operator = (const OdPrcObjectId& elementId)     { m_Id = elementId.m_Id; return *this; }

  /** \details
  An assignment operator for <link OdPrcObjectId, PRC object identifiers>.
  Assigns the value from a specified stub object to this <link OdPrcObjectId, PRC object identifier>.
  \param objectId [in] A raw pointer to the stub object that contains the identifier value.
  \returns A reference to the <link OdPrcObjectId, PRC object identifier> modified by the assignment operation.
  */  
  OdPrcObjectId& operator = (OdDbStub* objectId)               { m_Id = objectId; return *this; }

  /** \details
  An assignment operator for <link OdPrcObjectId, PRC object identifiers>.
  Compares this <link OdPrcObjectId, PRC object identifier> with a value of another <link OdPrcObjectId, PRC object identifier>.
  \param elementId [in] Another <link OdPrcObjectId, PRC object identifier> to compare with (the right-hand operand of the comparison operation).
  \returns A Boolean value that is equal to true if the value of this <link OdPrcObjectId, PRC object identifier> is equal to another <link OdPrcObjectId, PRC object identifier>; otherwise, the operator returns false.
  */    
  bool operator == (const OdPrcObjectId& elementId) const;

  /** \details
  A &quot;more than&quot; operator for <link OdPrcObjectId, PRC object identifiers>.
  \param elementId [in] Another <link OdPrcObjectId, PRC object identifier> to compare with (the right-hand operand of the comparison operation).
  \returns A Boolean value that is equal to true if the value of this <link OdPrcObjectId, PRC object identifier> is more than another <link OdPrcObjectId, PRC object identifier>; otherwise, the operator returns false.
  */    
  bool operator > (const OdPrcObjectId& elementId) const;

  /** \details
  A &quot;less than&quot; operator for <link OdPrcObjectId, PRC object identifiers>.
  \param elementId [in] Another <link OdPrcObjectId, PRC object identifier> to compare with (the right-hand operand of the comparison operation).
  \returns A Boolean value that is equal to true if the value of this <link OdPrcObjectId, PRC object identifier> is less than another <link OdPrcObjectId, PRC object identifier>; otherwise, the operator returns false.
  */    
  bool operator < (const OdPrcObjectId& elementId) const;

  /** \details
  Checks whether the <link OdPrcObjectId, PRC object identifier> is NULL. 
  \return A Boolean value that is equal to true if the <link OdPrcObjectId, PRC object identifier> is empty (NULL); otherwise, the operator returns false.
  */    
  bool operator !() const { return isNull(); }

  //DOM-IGNORE-BEGIN
  /**\details 
  Requests the stub object associated with the <link OdPrcObjectId, PRC object identifier>. 
  \returns A raw pointer to the stub object associated with the <link OdPrcObjectId, PRC object identifier>. 
  \remarks
  This method is for PRC SDK internal use only. Please do NOT use it in your applications.
  */
  inline operator OdDbStub*() const   { return (OdDbStub*) m_Id; }
  //DOM-IGNORE-END

  /** \details
  Requests the database that contains the PRC entity the <link OdPrcObjectId, PRC object identifier> refers to.
  \returns A raw pointer to the database that contains the PRC entity the <link OdPrcObjectId, PRC object identifier> refers to. 
           The database is represented by an object of the <exref target="https://docs.opendesign.com/tkernel/OdDbBaseDatabase.html">OdDbBaseDatabase</exref> or any derived class.
  \remarks 
  The method returns a NULL value if the <link OdPrcObjectId, PRC object identifier> is not associated with a database.
  The <exref target="https://docs.opendesign.com/tkernel/OdDbBaseDatabase.html">OdDbBaseDatabase</exref> is a type definition wrapper for the <exref target="https://docs.opendesign.com/tkernel/OdRxObject.html">OdRxObject</exref> class.
  \sa 
  * <exref target="https://docs.opendesign.com/tkernel/OdDbBaseDatabase.html">OdDbBaseDatabase</exref> type definition documentation.
  * <exref target="https://docs.opendesign.com/tkernel/OdRxObject.html">OdRxObject Class</exref> documentation.
  * <exref target="https://docs.opendesign.com/tkernel/rtti_overview.html">Overview of Classes that Implement RTTI</exref> in Kernel SDK documentation.
  */
  OdDbBaseDatabase* database() const;

  /**!DOM \details
  Returns the original database with which the PRC object identifier is associated.
  If the object associated with the identifier has been redirected to
  a host database from an externally referenced database, the method returns
  a pointer to the externally referenced database. 
  Otherwise, it returns a pointer to the database with which identifier is associated.
  */
  //OdBmDatabase* originalDatabase () const;

  /**!DOM \details
  If the identifier has been redirected from another database (for an example, an external reference), the method 
  returns the actual identifier from the original database.
  */
  //void convertToRedirectedId ();

  /**!DOM \details
  Returns true if an object associated with the identifier has been erased.
  */
  //bool isErased () const;

  /**!DOM \details
  Returns true if an PRC object, associated with the identifier, or any object from its ownership hierarchy, has been erased.
  */
  //bool isEffectivelyErased () const;

  /** \details
  Requests the <exref target="https://docs.opendesign.com/tkernel/OdDbHandle.html">database handle</exref> of the object referenced by the <link OdPrcObjectId, PRC object identifier>.
  
  \returns An <exref target="https://docs.opendesign.com/tkernel/OdDbHandle.html">OdDbHandle</exref> object that represents the database handle.
    
  \remarks
  The method returns NULL if no database object is referenced by the <link OdPrcObjectId, PRC object identifier>.
  If the <link OdPrcObjectId, identifier> is redirected from another database (for example, an external reference), the method returns the 
  <exref target="https://docs.opendesign.com/tkernel/OdDbHandle.html">handle</exref> from the original database.
  */
  const OdDbHandle& getHandle() const;

  /**!DOM \details
  Returns the database handle of the object referenced by the identifier.
  
  \remarks
  Returns NULL if no database object is referenced by the identifier.

  If this identifier has been redirected from another database (for example, an external reference), the method 
  returns the handle from the original database.
  */
  //const OdDbHandle& getNonForwardedHandle () const;

  /**!DOM \details
  Opens the database object associated with the identifier.

  \param pObj [out]  Smart pointer to the object to be opened.
  \param openMode [in]  Mode in which the object must be opened.
  \param openErasedOne [in]  Specifies whether erased objects are also opened (true) or not (false).

  \returns Returns eOk if successful, otherwise returns an Error Code.
  
  \remarks
  openMode must be one of the following:
  <table>
    Identifier    Value     Description
    kNotOpen      -1        Object is open for reading.
    kForRead      0         Object is open for reading.
    kForWrite     1         Object is open for reading and/or writing.
    kForNotify    2         Object is open for notifying.    
  </table>
  */
  //OdResult openObject (
  //  OdBmObjectPtr& pObj,
  //  OdBm::OpenMode openMode = OdBm::kForRead, 
  //  bool openErasedOne = false) const;
  
  /** \details
  Opens the database object associated with the <link OdPrcObjectId, identifier>.
  
  \param pObj           [out] A smart pointer that acts as a placeholder for the opened object.
  \param openMode       [in]  A value that defines the <link OpenMode, access type> for the opened object.
  \param openErasedOne  [in]  A flag that determines whether the method opens erased objects as well (when the flag value is equal to true) or not (when the flag value is equal to false).

  \returns The eOk value if the object is successfully opened; otherwise, the method returns an appropriate error code.
  
  \remarks
  The <link OpenMode, access type> value (openMode parameter) must be one of the following:
  <table>
    <tr><th>Identifier</th> <th>Value</th>  <th>Description</th>
    <tr><td>kNotOpen</td>   <td>-1</td>     <td>The object is not open.</td></tr>
    <tr><td>kForRead</td>   <td>0</td>      <td>The object is open for reading.</td></tr>
    <tr><td>kForWrite</td>  <td>1</td>      <td>The object is open for reading and/or writing.</td></tr>
    <tr><td>kForNotify</td> <td>2</td>      <td>The object is open for notifications.</td></tr>
  </table>
  */
  OdResult openObject(
    OdRxObjectPtr& pObj,
    OpenMode openMode = kForRead, 
    bool openErasedOne = false) const;
    
  /** \details
  Opens the database object associated with the <link OdPrcObjectId, identifier>.

  \param openMode       [in]  A value that defines the <link OpenMode, access type> for the opened object.
  \param openErasedOne  [in]  A flag that determines whether the method opens erased objects as well (when the flag value is equal to true) or not (when the flag value is equal to false).

  \returns A smart pointer to the opened object if it is successfully opened; otherwise, the method returns a NULL pointer.
    
  \remarks
  The <link OpenMode, access type> value (openMode parameter) must be one of the following:
  <table>
    <tr><th>Identifier</th> <th>Value</th>  <th>Description</th>
    <tr><td>kNotOpen</td>   <td>-1</td>     <td>The object is not open.</td></tr>
    <tr><td>kForRead</td>   <td>0</td>      <td>The object is open for reading.</td></tr>
    <tr><td>kForWrite</td>  <td>1</td>      <td>The object is open for reading and/or writing.</td></tr>
    <tr><td>kForNotify</td> <td>2</td>      <td>The object is open for notifications.</td></tr>
  </table>
  */
  OdRxObjectPtr openObject(
    OpenMode openMode = kForRead, 
    bool openErasedOne = false) const;
    
  /** \details
  Safely opens the database object associated with the <link OdPrcObjectId, identifier>.

  \param openMode       [in]  A value that defines the <link OpenMode, access type> for the opened object.
  \param openErasedOne  [in]  A flag that determines whether the method opens erased objects as well (when the flag value is equal to true) or not (when the flag value is equal to false).

  \returns A smart pointer to the opened object if it is successfully opened; otherwise, the method returns a NULL pointer.
  
  \remarks
  The <link OpenMode, access type> value (openMode parameter) must be one of the following:
  <table>
    <tr><th>Identifier</th> <th>Value</th>  <th>Description</th>
    <tr><td>kNotOpen</td>   <td>-1</td>     <td>The object is not open.</td></tr>
    <tr><td>kForRead</td>   <td>0</td>      <td>The object is open for reading.</td></tr>
    <tr><td>kForWrite</td>  <td>1</td>      <td>The object is open for reading and/or writing.</td></tr>
    <tr><td>kForNotify</td> <td>2</td>      <td>The object is open for notifications.</td></tr>
  </table>

  The method throws one of the following exceptions:
  <table>
  <tr><th>Exception Name</th>     <th>Exception Context</th></tr>
  <tr><td>eNullObjectId</td>      <td>The identifier is null.</td></tr>
  <tr><td>ePermanentlyErased</td> <td>The object was not opened (the openErasedOne parameter is equal to true).</td></tr>
  <tr><td>eWasErased</td>         <td>The object was not opened (the openErasedOne parameter is equal to false).</td></tr>
  </table>
  */
  OdRxObjectPtr safeOpenObject(OpenMode openMode = kForRead,
                              bool openErasedOne = false) const;

protected:
  friend class OdPrcStub;
  OdDbStub* m_Id;
};

/** \details 
A data type that represents an <exref target="https://docs.opendesign.com/tkernel/OdArray@classT@classA.html">array</exref> 
of <link OdPrcObjectId, PRC object identifiers>.  
*/
typedef OdArray<OdPrcObjectId> OdPrcObjectIdArray;

#endif // _PRCOBJECTID_