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


#include "TD_PackPush.h"

#include "DbBaseHostAppServices.h"
#include "StringArray.h"

class OdPrcFile;
typedef OdSmartPtr<OdPrcFile> OdPrcFilePtr;

class wrTriangulationParams;

/** \details 
This class is the base class for platform-specific operations within PRC SDK.
<group PRC_Base_Classes>
*/
class ODRX_ABSTRACT PRC_TOOLKIT OdPrcHostAppServices : public OdDbBaseHostAppServices {
public:
  //DOM-IGNORE-BEGIN
  ODRX_DECLARE_MEMBERS(OdPrcHostAppServices);
  //DOM-IGNORE-END

  /** \details 
  Creates platform-specific operations services for PRC file functionality. 
  */
  OdPrcHostAppServices();

  /** \details 
  Enumeration for default database content initialization modes.
  */
  enum DatabaseDefaultContent
  {
    /** Database content is not to be initialized.*/
    kDbNotInitialized   = 0,  
  /** Default database content initialization mode.*/
    kDbDefault          = 1   
  };

  /** \details
  Requests the static <exref target="https://docs.opendesign.com/tkernel/OdRxClass.html">OdRxClass</exref> description object associated with the database.

  \returns The result of the OdPrcFile::desc() method inherited from the <exref target="https://docs.opendesign.com/tkernel/OdRxObject.html">OdRxObject</exref> object.
  */
  virtual OdRxClass* databaseClass() const;

  /** \details 
  Creates an instance of the <link OdPrcFile, OdPrcFile> class.

  \param defaultContent [in] A default database content flag. It determines whether the newly created database is populated with the default set of objects.
  If the parameter value is equal to kNotInitialized, the database default content is not initialized.

  \returns The smart pointer to the newly created database.
  
  \remarks
  This HostAppServices object will be associated with the newly created database.

   */
  virtual OdPrcFilePtr createDatabase(
    DatabaseDefaultContent defaultContent = kDbDefault) const;

  /** \details 
  Requests the fully qualified path to the specified file.

  \param filename [in] A name of the file to find.
  \param pDb      [in] A pointer to the database context. If the parameter value is equal to NULL, the file search is not related to a database.
  \param hint     [in] A hint that indicates the type of file that is required.

  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the full path to the file.
    
  \remarks 
  The method returns an empty <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> if the file is not found.

  This method is called by PRC SDK when access is needed to a
  file, such as a font file, a template file, etc.

  If the pDb parameter value is not equal to NULL, call pDb->getFilename() to determine the path to the PRC file associated with the database.

  The typical search order is as follows:

# The file name itself.
# The current directory.
# The drawing directory (for shx font, image, and xref files).
# The Windows fonts directory (only for TTF fonts on Windows).

  The hint parameter must be one of the following:
  
  <table>
  Name                    Value     Description Extension
  kDefault                0         Any file.                         any
  kFontFile               1         Can be either SHX or TTF file.    SHX or TTF
  kCompiledShapeFile      2         SHX file.                         SHX
  kTrueTypeFontFile       3         TTF file.                         TTF
  kEmbeddedImageFile      4         Image file.                       ISM
  kXRefDrawing            5         External reference file.
  kPatternFile            6         Pattern file (PAT)                PAT
  kDRXApplication         7         DRX application file.             DRX
  kFontMapFile            8         FontMap file.                     FMP
  </table>
  */
  virtual OdString findFile(
    const OdString& filename,
    OdDbBaseDatabase* pDb = 0,
    FindFileHint hint = kDefault);

  /** \details 
  Requests the current name of the client program.
  This method is typically used for populating the &quot;About&quot; information.
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the current name of the client program.
  \remarks 
  The default implementation of this method returns the result of <exref target="https://docs.opendesign.com/td/oddgGetLibraryInfo.html">oddgGetLibraryInfo()</exref>
  -><exref target="https://docs.opendesign.com/tkernel/OdDbLibraryInfo__getLibName@const.html">getLibName()</exref>.
  */
  virtual const OdString program();

  /** \details 
  Requests the current name of the client product.
  This method is typically used for populating the &quot;About&quot; information.
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the current name of the client product.
  \remarks
  The default implementation of this method returns the result of the <link OdPrcHostAppServices::program, program()> method of the <link OdPrcHostAppServices, OdPrcHostAppServices> class.
  */
  virtual const OdString product();

  /** \details
  Requests the current name of the client company.
  This method is typically used for populating the &quot;About&quot; information.
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the current name of the client company.
  \remarks 
  The default implementation of this method returns the result of <exref target="https://docs.opendesign.com/td/oddgGetLibraryInfo.html">oddgGetLibraryInfo()</exref>
  -><exref target="https://docs.opendesign.com/tkernel/OdDbLibraryInfo__getCompanyName@const.html">getCompanyName()</exref>.  
  */
  virtual const OdString companyName();

  /** \details 
  Requests the major and minor release version numbers of the client application in string form.
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the major and minor release version numbers of the client application.  
  \remarks
  The default implementation of this method returns the result of <exref target="https://docs.opendesign.com/td/oddgGetLibraryInfo.html">oddgGetLibraryInfo()</exref>
  -><exref target="https://docs.opendesign.com/tkernel/OdDbLibraryInfo__getLibVersion@const.html">getLibVersion()</exref>.  
  */
  virtual const OdString releaseMajorMinorString();

  /** \details 
  Requests a string that contains the release version of the client application.
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the release version information of the client application.  
  \remarks
  The default implementation of this method returns the result of <exref target="https://docs.opendesign.com/td/oddgGetLibraryInfo.html">oddgGetLibraryInfo()</exref>
  -><exref target="https://docs.opendesign.com/tkernel/OdDbLibraryInfo__getLibVersion@const.html">getLibVersion()</exref>.
  */
  virtual const OdString versionString();

  /** \details
  Generates a string that contains a formatted message corresponding to the specified error code(s).
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the formatted error message.
  \param errorCode [in] An error code. The method accepts multiple error codes as well, but at least one.
   */
  virtual OdString formatMessage(
    unsigned int errorCode,...);

  /** \details 
  Requests the path to an alternate font file to be used when a given font file is not found by PRC SDK.
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the full path to the file that contains the alternate font.
  \remarks
  The default implementation of this method returns an empty <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref>.
  \sa
  <link prc_getting_started_font_handling, Usage of Fonts>
  */
  virtual OdString getAlternateFontName() const;

  /** \details 
  Requests the name of the font mapping file used by the <link OdPrcHostAppServices::getPreferableFont@const_OdString&@OdFontType, getPreferableFont()> method.
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the full path to the font mapping file.
  \remarks 
  The default implementation of this method returns an empty <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref>.
  
  \sa
  <link prc_getting_started_font_handling, Usage of Fonts>
  */
  virtual OdString getFontMapFileName() const;

  /** \details 
  Requests the preferred font name for the specified font name and type.

  \param fontName [in] A font name.
  \param fontType [in] A font type.
  
  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the preferred font name.
  
  \remarks
  The fontType parameter value must be one of the following:
  
  <table>
  Name                    Value    Description
  kFontTypeUnknown        0        Unknown.
  kFontTypeShx            1        SHX font.
  kFontTypeTrueType       2        TrueType font.
  kFontTypeShape          3        Shape file.
  kFontTypeBig            4        BigFont file.
  </table>

  The default implementation of this method returns an empty <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref>.
  
  \sa
  <link prc_getting_started_font_handling, Usage of Fonts>
  */
  virtual OdString getPreferableFont(
    const OdString& fontName,
    OdFontType fontType);

  /** \details 
  Requests the name of the substitute font to be used when the specified font is not found.

  \param fontName [in] A font name.
  \param fontType [in] A font type.

  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the substitute font name.
  
  \remarks 
  The fontType parameter value must be one of the following:

  <table>
  Name                    Value    Description
  kFontTypeUnknown        0        Unknown.
  kFontTypeShx            1        SHX font.
  kFontTypeTrueType       2        TrueType font.
  kFontTypeShape          3        Shape file.
  kFontTypeBig            4        BigFont file.
  </table>

  The default implementation of this method returns an empty <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref>.
  
  \sa 
  <link prc_getting_started_font_handling, Usage of Fonts>
  */
  virtual OdString getSubstituteFont(
    const OdString& fontName,
    OdFontType fontType);

  /** \details
  Requests the typeface name of the substitute TrueType font that contains the specified character when a specified font is not found by the operating system.
  
  \param pFont        [in] The current <exref target="">font</exref>.
  \param unicodeChar  [in] The symbol (Unicode) that should be found in the substitute font.
  \param pDb          [in] A pointer to the database context.

  \returns A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the typeface name of the substitute font.
  
  \remarks
  The default implementation uses Windows API for getting the font.
  
  \sa
  <link prc_getting_started_font_handling, Usage of Fonts>
  */
  virtual OdString getSubstituteFontByChar(
    const OdFont& pFont,
    OdChar unicodeChar, OdDbBaseDatabase *pDb);

  /** \details
  Requests the <exref target="https://docs.opendesign.com/tv/OdGsDevice.html">bitmap device</exref> associated with this <link OdPrcHostAppServices, OdPrcHostAppServices> object.

  \param pViewObj [in]  An <exref target="https://docs.opendesign.com/tkernel/OdAbstractViewPE.html">OdAbstractViewPE</exref>-compatible object 
                        (for example, <exref target="https://docs.opendesign.com/tv/OdGsView.html">OdGsView</exref>, etc.).
  \param pDb      [in]  A pointer to the database context.
  \param flags    [in]  An unsigned 32-bit integer that contains the <exref target="https://docs.opendesign.com/tv/OdGsDevice.html">bitmap device</exref> flags.
  
  \returns A smart pointer to the <exref target="https://docs.opendesign.com/tv/OdGsDevice.html">OdGsDevice</exref> object.
  */
  virtual OdGsDevicePtr gsBitmapDevice(
    OdRxObject* pViewObj = NULL,
    OdDbBaseDatabase* pDb = NULL,
    OdUInt32 flags = 0);

  /** \details
  Reads PRC file content from a specified stream and returns a smart pointer to the created <link OdPrcFile, OdPrcFile> object. 
  
  \param pFileBuff [in] A raw pointer to a stream to read data from.
  \returns A smart pointer to an <link OdPrcFile, OdPrcFile> object that contains the read data.
  */
  virtual OdPrcFilePtr readFile(OdStreamBuf* pFileBuff);

  /** \details
  Reads content from a specified PRC file, creates a new <link OdPrcFile, OdPrcFile> object, and returns a smart pointer to it. 
  
  \param file [in] A path to the file to read data from.
  \returns A smart pointer to an <link OdPrcFile, OdPrcFile> object that contains the read data.
  */
  virtual OdPrcFilePtr readFile(const OdString &file);

  /** \details
  Sets a new global setting of the B-Rep triangulation.
  \param params [out] An object that contains the settings to be applied.
  \returns eOk if the new settings were successfully set; otherwise, the method returns an appropriate error code.
  */
  virtual OdResult setTriangulationParams(const wrTriangulationParams &params);

  /** \details
  Retrieves the global setting of the B-Rep triangulation.
  \param params [out] A placeholder for the global settings of the B-Rep triangulation.
  \returns eOk if the settings were successfully returned; otherwise, the method returns an appropriate error code.
  */
  virtual OdResult getTriangulationParams(wrTriangulationParams &params);

  /** \details
  Initializes a <exref target="https://docs.opendesign.com/tkernel/OdBrepBuilder.html">B-Rep Builder</exref> object with a product-specific implementation. 

  \param bbuilder [in] A placeholder for the instance of the <exref target="https://docs.opendesign.com/tkernel/OdBrepBuilder.html">B-Rep builder class</exref>.
  \param bbType   [in] A <exref target="https://docs.opendesign.com/tkernel/BrepType.html">type</exref> of B-Rep object.
  \returns The eOk value if the <exref target="https://docs.opendesign.com/tkernel/OdBrepBuilder.html">B-Rep builder</exref> object was successfully initialized; otherwise, the method returns an appropriate error code.
  \remarks 
  The method returns eNotImplementedYet by default.
  */
  virtual OdResult brepBuilder(OdBrepBuilder& bbuilder, BrepType bbType);
};

#include "TD_PackPop.h"

#endif /* _ODPRC_HOSTAPPLICATIONSERVICES_INCLUDED_ */